Require docs for public members (#614)

progenitor-client/src/lib.rs

@@ -1,5 +1,9 @@
 // Copyright 2022 Oxide Computer Company
 
+//! Support for generated clients.
+
+#![deny(missing_docs)]
+
 mod progenitor_client;
 
 pub use crate::progenitor_client::*;

progenitor-client/src/progenitor_client.rs

@@ -401,6 +401,7 @@ const PATH_SET: &percent_encoding::AsciiSet = &percent_encoding::CONTROLS
     .add(b'%');
 
 #[doc(hidden)]
+/// Percent encode input string.
 pub fn encode_path(pc: &str) -> String {
     percent_encoding::utf8_percent_encode(pc, PATH_SET).to_string()
 }

progenitor-impl/src/lib.rs

@@ -1,7 +1,10 @@
 // Copyright 2024 Oxide Computer Company
 
-use std::collections::BTreeMap;
-use std::collections::{HashMap, HashSet};
+//! Core implementation for the progenitor OpenAPI client generator.
+
+#![deny(missing_docs)]
+
+use std::collections::{BTreeMap, HashMap, HashSet};
 
 use openapiv3::OpenAPI;
 use proc_macro2::TokenStream;
@@ -22,6 +25,7 @@ mod template;
 mod to_schema;
 mod util;
 
+#[allow(missing_docs)]
 #[derive(Error, Debug)]
 pub enum Error {
     #[error("unexpected value type {0}: {1}")]
@@ -38,8 +42,10 @@ pub enum Error {
     InternalError(String),
 }
 
+#[allow(missing_docs)]
 pub type Result<T> = std::result::Result<T, Error>;
 
+/// OpenAPI generator.
 pub struct Generator {
     type_space: TypeSpace,
     settings: GenerationSettings,
@@ -47,6 +53,7 @@ pub struct Generator {
     uses_websockets: bool,
 }
 
+/// Settings for [Generator].
 #[derive(Default, Clone)]
 pub struct GenerationSettings {
     interface: InterfaceStyle,
@@ -61,9 +68,12 @@ pub struct GenerationSettings {
     convert: Vec<(schemars::schema::SchemaObject, String, Vec<TypeImpl>)>,
 }
 
+/// Style of generated client.
 #[derive(Clone, Deserialize, PartialEq, Eq)]
 pub enum InterfaceStyle {
+    /// Use positional style.
     Positional,
+    /// Use builder style.
     Builder,
 }
 
@@ -73,9 +83,12 @@ impl Default for InterfaceStyle {
     }
 }
 
+/// Style for using the OpenAPI tags when generating names in the client.
 #[derive(Clone, Deserialize)]
 pub enum TagStyle {
+    /// Merge tags to create names in the generated client.
     Merged,
+    /// Use each tag name to create separate names in the generated client.
     Separate,
 }
 
@@ -86,40 +99,49 @@ impl Default for TagStyle {
 }
 
 impl GenerationSettings {
+    /// Create new generator settings with default values.
     pub fn new() -> Self {
         Self::default()
     }
 
+    /// Set the [InterfaceStyle].
     pub fn with_interface(&mut self, interface: InterfaceStyle) -> &mut Self {
         self.interface = interface;
         self
     }
 
+    /// Set the [TagStyle].
     pub fn with_tag(&mut self, tag: TagStyle) -> &mut Self {
         self.tag = tag;
         self
     }
 
+    /// Client inner type available to pre and post hooks.
     pub fn with_inner_type(&mut self, inner_type: TokenStream) -> &mut Self {
         self.inner_type = Some(inner_type);
         self
     }
 
+    /// Hook invoked before issuing the HTTP request.
     pub fn with_pre_hook(&mut self, pre_hook: TokenStream) -> &mut Self {
         self.pre_hook = Some(pre_hook);
         self
     }
 
+    /// Hook invoked prior to receiving the HTTP response.
     pub fn with_post_hook(&mut self, post_hook: TokenStream) -> &mut Self {
         self.post_hook = Some(post_hook);
         self
     }
 
+    /// Additional derive macros applied to generated types.
     pub fn with_derive(&mut self, derive: impl ToString) -> &mut Self {
         self.extra_derives.push(derive.to_string());
         self
     }
 
+    /// Modify a type with the given name.
+    /// See [typify::TypeSpaceSettings::with_patch].
     pub fn with_patch<S: AsRef<str>>(
         &mut self,
         type_name: S,
@@ -130,6 +152,8 @@ impl GenerationSettings {
         self
     }
 
+    /// Replace a referenced type with a named type.
+    /// See [typify::TypeSpaceSettings::with_replacement].
     pub fn with_replacement<
         TS: ToString,
         RS: ToString,
@@ -147,6 +171,8 @@ impl GenerationSettings {
         self
     }
 
+    /// Replace a given schema with a named type.
+    /// See [typify::TypeSpaceSettings::with_conversion].
     pub fn with_conversion<S: ToString, I: Iterator<Item = TypeImpl>>(
         &mut self,
         schema: schemars::schema::SchemaObject,
@@ -173,6 +199,7 @@ impl Default for Generator {
 }
 
 impl Generator {
+    /// Create a new generator with default values.
     pub fn new(settings: &GenerationSettings) -> Self {
         let mut type_settings = TypeSpaceSettings::default();
         type_settings
@@ -211,6 +238,7 @@ impl Generator {
         }
     }
 
+    /// Emit a [TokenStream] containing the generated client code.
     pub fn generate_tokens(&mut self, spec: &OpenAPI) -> Result<TokenStream> {
         validate_openapi(spec)?;
 
@@ -522,22 +550,24 @@ impl Generator {
         Ok(out)
     }
 
-    // TODO deprecate?
+    /// Get the [TypeSpace] for schemas present in the OpenAPI specification.
     pub fn get_type_space(&self) -> &TypeSpace {
         &self.type_space
     }
 
+    /// Whether the generated client needs to use additional crates to support futures.
     pub fn uses_futures(&self) -> bool {
         self.uses_futures
     }
 
+    /// Whether the generated client needs to use additional crates to support websockets.
     pub fn uses_websockets(&self) -> bool {
         self.uses_websockets
     }
 }
 
+/// Add newlines after end-braces at <= two levels of indentation.
 pub fn space_out_items(content: String) -> Result<String> {
-    // Add newlines after end-braces at <= two levels of indentation.
     Ok(if cfg!(not(windows)) {
         let regex = regex::Regex::new(r#"(\n\s*})(\n\s{0,8}[^} ])"#).unwrap();
         regex.replace_all(&content, "$1\n$2").to_string()

progenitor-macro/src/lib.rs

@@ -1,5 +1,9 @@
 // Copyright 2022 Oxide Computer Company
 
+//! Macros for the progenitor OpenAPI client generator.
+
+#![deny(missing_docs)]
+
 use std::{
     collections::HashMap,
     fmt::Display,

progenitor/src/lib.rs

@@ -10,6 +10,8 @@
 //! For details see the [repo
 //! README](https://github.com/oxidecomputer/progenitor/blob/main/README.md)
 
+#![deny(missing_docs)]
+
 pub use progenitor_client;
 pub use progenitor_impl::Error;
 pub use progenitor_impl::GenerationSettings;