Require docs for public members

cargo-typify/src/lib.rs

@@ -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};
@@ -38,6 +42,7 @@ pub struct CliArgs {
 }
 
 impl CliArgs {
+    /// Output path.
     pub fn output_path(&self) -> Option<PathBuf> {
         match &self.output {
             Some(output_path) => {
@@ -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()))?;

typify-impl/src/lib.rs

@@ -1,5 +1,9 @@
 // Copyright 2023 Oxide Computer Company
 
+//! typify backend implementation.
+
+#![deny(missing_docs)]
+
 use std::collections::{BTreeMap, BTreeSet};
 
 use conversions::SchemaCache;
@@ -32,6 +36,7 @@ mod util;
 mod validate;
 mod value;
 
+#[allow(missing_docs)]
 #[derive(Error, Debug)]
 pub enum Error {
     #[error("unexpected value type")]
@@ -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 {
@@ -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>),
@@ -94,13 +101,15 @@ pub struct TypeEnum<'a> {
     details: &'a type_entry::TypeEntryEnum,
 }
 
+#[allow(missing_docs)]
 /// Enum variant details.
 pub enum TypeEnumVariant<'a> {
     Simple,
     Tuple(Vec<TypeId>),
     Struct(Vec<(&'a str, TypeId)>),
 }
 
+#[allow(missing_docs)]
 pub struct TypeEnumVariantInfo<'a> {
     pub name: &'a str,
     pub description: Option<&'a str>,
@@ -112,6 +121,7 @@ pub struct TypeStruct<'a> {
     details: &'a type_entry::TypeEntryStruct,
 }
 
+#[allow(missing_docs)]
 pub struct TypeStructPropInfo<'a> {
     pub name: &'a str,
     pub description: Option<&'a str>,
@@ -251,6 +261,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)]
@@ -606,18 +617,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
     }
@@ -871,10 +886,12 @@ impl<'a> Type<'a> {
 }
 
 impl<'a> TypeEnum<'a> {
+    /// Get name and information of each variant.
     pub fn variants(&'a self) -> impl Iterator<Item = (&'a str, TypeEnumVariant<'a>)> {
         self.variants_info().map(|info| (info.name, info.details))
     }
 
+    /// Get information for each variant.
     pub fn variants_info(&'a self) -> impl Iterator<Item = TypeEnumVariantInfo<'a>> {
         self.details.variants.iter().map(move |variant| {
             let details = match &variant.details {
@@ -902,13 +919,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 information about each property.
     pub fn properties_info(&'a self) -> impl Iterator<Item = TypeStructPropInfo> {
         self.details
             .properties
@@ -923,6 +942,7 @@ impl<'a> TypeStruct<'a> {
 }
 
 impl<'a> TypeNewtype<'a> {
+    /// Get subtype.
     pub fn subtype(&self) -> TypeId {
         self.details.type_id.clone()
     }

typify-macro/src/lib.rs

@@ -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;

typify/src/lib.rs

@@ -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;