Skip to content

Commit

Permalink
Require docs for public members (#427)
Browse files Browse the repository at this point in the history
  • Loading branch information
jayvdb authored Nov 3, 2023
1 parent c21dc2e commit 5f9235d
Show file tree
Hide file tree
Showing 4 changed files with 43 additions and 1 deletion.
7 changes: 7 additions & 0 deletions cargo-typify/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
// Copyright 2023 Oxide Computer Company

//! cargo command to generate Rust code from a JSON Schema.
#![deny(missing_docs)]

use std::path::PathBuf;

use clap::{ArgGroup, Args};
Expand Down Expand Up @@ -38,6 +42,7 @@ pub struct CliArgs {
}

impl CliArgs {
/// Output path.
pub fn output_path(&self) -> Option<PathBuf> {
match &self.output {
Some(output_path) => {
Expand All @@ -55,11 +60,13 @@ impl CliArgs {
}
}

/// Whether builder-style interface was selected.
pub fn use_builder(&self) -> bool {
!self.no_builder
}
}

/// Generate Rust code for the selected JSON Schema.
pub fn convert(args: &CliArgs) -> Result<String> {
let content = std::fs::read_to_string(&args.input)
.wrap_err_with(|| format!("Failed to open input file: {}", &args.input.display()))?;
Expand Down
31 changes: 30 additions & 1 deletion typify-impl/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
// Copyright 2023 Oxide Computer Company

//! typify backend implementation.
#![deny(missing_docs)]

use std::collections::{BTreeMap, BTreeSet};

use conversions::SchemaCache;
Expand Down Expand Up @@ -32,6 +36,7 @@ mod util;
mod validate;
mod value;

#[allow(missing_docs)]
#[derive(Error, Debug)]
pub enum Error {
#[error("unexpected value type")]
Expand All @@ -53,6 +58,7 @@ impl Error {
}
}

#[allow(missing_docs)]
pub type Result<T> = std::result::Result<T, Error>;

fn show_type_name(type_name: Option<&str>) -> &str {
Expand All @@ -70,6 +76,7 @@ pub struct Type<'a> {
type_entry: &'a TypeEntry,
}

#[allow(missing_docs)]
/// Type details returned by Type::details() to inspect a type.
pub enum TypeDetails<'a> {
Enum(TypeEnum<'a>),
Expand All @@ -96,14 +103,21 @@ pub struct TypeEnum<'a> {

/// Enum variant details.
pub enum TypeEnumVariant<'a> {
/// Variant with no associated data.
Simple,
/// Tuple-type variant with at least one associated type.
Tuple(Vec<TypeId>),
/// Struct-type variant with named properties and types.
Struct(Vec<(&'a str, TypeId)>),
}

/// Full information pertaining to an enum variant.
pub struct TypeEnumVariantInfo<'a> {
/// Name.
pub name: &'a str,
/// Description.
pub description: Option<&'a str>,
/// Details for the enum variant.
pub details: TypeEnumVariant<'a>,
}

Expand All @@ -112,10 +126,15 @@ pub struct TypeStruct<'a> {
details: &'a type_entry::TypeEntryStruct,
}

/// Full information pertaining to a struct property.
pub struct TypeStructPropInfo<'a> {
/// Name.
pub name: &'a str,
/// Description.
pub description: Option<&'a str>,
/// Whether the propertty is required.
pub required: bool,
/// Identifies the schema for the property.
pub type_id: TypeId,
}

Expand Down Expand Up @@ -251,6 +270,7 @@ struct TypeSpaceConversion {
impls: Vec<TypeSpaceImpl>,
}

#[allow(missing_docs)]
// TODO we can currently only address traits for which cycle analysis is not
// required.
#[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
Expand Down Expand Up @@ -606,18 +626,22 @@ impl TypeSpace {
})
}

/// Whether the generated code needs `chrono` crate.
pub fn uses_chrono(&self) -> bool {
self.uses_chrono
}

/// Whether the generated code needs [regress] crate.
pub fn uses_regress(&self) -> bool {
self.uses_regress
}

/// Whether the generated code needs [serde_json] crate.
pub fn uses_serde_json(&self) -> bool {
self.uses_serde_json
}

/// Whether the generated code needs `uuid` crate.
pub fn uses_uuid(&self) -> bool {
self.uses_uuid
}
Expand Down Expand Up @@ -871,10 +895,12 @@ impl<'a> Type<'a> {
}

impl<'a> TypeEnum<'a> {
/// Get name and information of each enum variant.
pub fn variants(&'a self) -> impl Iterator<Item = (&'a str, TypeEnumVariant<'a>)> {
self.variants_info().map(|info| (info.name, info.details))
}

/// Get all information for each enum variant.
pub fn variants_info(&'a self) -> impl Iterator<Item = TypeEnumVariantInfo<'a>> {
self.details.variants.iter().map(move |variant| {
let details = match &variant.details {
Expand Down Expand Up @@ -902,13 +928,15 @@ impl<'a> TypeEnum<'a> {
}

impl<'a> TypeStruct<'a> {
/// Get name and type of each property.
pub fn properties(&'a self) -> impl Iterator<Item = (&'a str, TypeId)> {
self.details
.properties
.iter()
.map(move |prop| (prop.name.as_str(), prop.type_id.clone()))
}

/// Get all information about each struct property.
pub fn properties_info(&'a self) -> impl Iterator<Item = TypeStructPropInfo> {
self.details
.properties
Expand All @@ -923,7 +951,8 @@ impl<'a> TypeStruct<'a> {
}

impl<'a> TypeNewtype<'a> {
pub fn subtype(&self) -> TypeId {
/// Get the inner type of the newtype struct.
pub fn inner(&self) -> TypeId {
self.details.type_id.clone()
}
}
Expand Down
4 changes: 4 additions & 0 deletions typify-macro/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
// Copyright 2023 Oxide Computer Company

//! typify macro implementation.
#![deny(missing_docs)]

use std::{collections::HashMap, path::Path};

use proc_macro::TokenStream;
Expand Down
2 changes: 2 additions & 0 deletions typify/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,8 @@
//! more information, see the project's
//! [README.md](https://github.com/oxidecomputer/typify).
#![deny(missing_docs)]

pub use typify_impl::Error;
pub use typify_impl::Type;
pub use typify_impl::TypeDetails;
Expand Down

0 comments on commit 5f9235d

Please sign in to comment.