From 8088f55470c2dbc7a50b89e2404b997d72f37dab Mon Sep 17 00:00:00 2001
From: Adam Leventhal <ahl@oxide.computer>
Date: Sat, 6 Jan 2024 01:01:12 -0800
Subject: [PATCH] add docs to mods and extension traits (#677)

---
 progenitor-impl/src/lib.rs                    | 21 ++++++++++++---
 progenitor-impl/src/method.rs                 |  8 +++++-
 .../tests/output/buildomat-builder-tagged.out |  4 +++
 .../tests/output/buildomat-builder.out        |  3 +++
 .../tests/output/buildomat-positional.out     |  2 ++
 .../tests/output/keeper-builder-tagged.out    |  4 +++
 .../tests/output/keeper-builder.out           |  3 +++
 .../tests/output/keeper-positional.out        |  2 ++
 .../tests/output/nexus-builder-tagged.out     | 27 +++++++++++++++++++
 .../tests/output/nexus-builder.out            |  3 +++
 .../tests/output/nexus-positional.out         |  2 ++
 .../output/param-collision-builder-tagged.out |  4 +++
 .../tests/output/param-collision-builder.out  |  3 +++
 .../output/param-collision-positional.out     |  2 ++
 .../output/param-overrides-builder-tagged.out |  4 +++
 .../tests/output/param-overrides-builder.out  |  3 +++
 .../output/param-overrides-positional.out     |  2 ++
 .../output/propolis-server-builder-tagged.out |  4 +++
 .../tests/output/propolis-server-builder.out  |  3 +++
 .../output/propolis-server-positional.out     |  2 ++
 .../output/test_default_params_builder.out    |  3 +++
 .../output/test_default_params_positional.out |  2 ++
 .../tests/output/test_freeform_response.out   |  2 ++
 .../tests/output/test_renamed_parameters.out  |  2 ++
 24 files changed, 110 insertions(+), 5 deletions(-)

diff --git a/progenitor-impl/src/lib.rs b/progenitor-impl/src/lib.rs
index adea626..acf8658 100644
--- a/progenitor-impl/src/lib.rs
+++ b/progenitor-impl/src/lib.rs
@@ -1,5 +1,6 @@
-// Copyright 2023 Oxide Computer Company
+// Copyright 2024 Oxide Computer Company
 
+use std::collections::BTreeMap;
 use std::collections::{HashMap, HashSet};
 
 use openapiv3::OpenAPI;
@@ -257,7 +258,12 @@ impl Generator {
                 self.generate_tokens_builder_merged(&raw_methods)
             }
             (InterfaceStyle::Builder, TagStyle::Separate) => {
-                self.generate_tokens_builder_separate(&raw_methods)
+                let tag_info = spec
+                    .tags
+                    .iter()
+                    .map(|tag| (&tag.name, tag))
+                    .collect::<BTreeMap<_, _>>();
+                self.generate_tokens_builder_separate(&raw_methods, tag_info)
             }
         }?;
 
@@ -318,6 +324,7 @@ impl Generator {
             #[allow(unused_imports)]
             use reqwest::header::{HeaderMap, HeaderValue};
 
+            /// Types used as operation parameters and responses.
             pub mod types {
                 use serde::{Deserialize, Serialize};
 
@@ -418,6 +425,7 @@ impl Generator {
                 #(#methods)*
             }
 
+            /// Items consumers will typically use such as the Client.
             pub mod prelude {
                 pub use super::Client;
             }
@@ -444,6 +452,7 @@ impl Generator {
                 #(#builder_methods)*
             }
 
+            /// Types for composing operation parameters.
             pub mod builder {
                 use super::types;
                 #[allow(unused_imports)]
@@ -460,6 +469,7 @@ impl Generator {
                 #(#builder_struct)*
             }
 
+            /// Items consumers will typically use such as the Client.
             pub mod prelude {
                 pub use self::super::Client;
             }
@@ -471,6 +481,7 @@ impl Generator {
     fn generate_tokens_builder_separate(
         &mut self,
         input_methods: &[method::OperationMethod],
+        tag_info: BTreeMap<&String, &openapiv3::Tag>,
     ) -> Result<TokenStream> {
         let builder_struct = input_methods
             .iter()
@@ -478,11 +489,12 @@ impl Generator {
             .collect::<Result<Vec<_>>>()?;
 
         let (traits_and_impls, trait_preludes) =
-            self.builder_tags(input_methods);
+            self.builder_tags(input_methods, &tag_info);
 
         let out = quote! {
             #traits_and_impls
 
+            /// Types for composing operation parameters.
             pub mod builder {
                 use super::types;
                 #[allow(unused_imports)]
@@ -497,9 +509,10 @@ impl Generator {
                 };
 
                 #(#builder_struct)*
-
             }
 
+            /// Items consumers will typically use such as the Client and
+            /// extension traits.
             pub mod prelude {
                 pub use super::Client;
                 #trait_preludes
diff --git a/progenitor-impl/src/method.rs b/progenitor-impl/src/method.rs
index c9dd43e..a530986 100644
--- a/progenitor-impl/src/method.rs
+++ b/progenitor-impl/src/method.rs
@@ -1,4 +1,4 @@
-// Copyright 2023 Oxide Computer Company
+// Copyright 2024 Oxide Computer Company
 
 use std::{
     cmp::Ordering,
@@ -2010,6 +2010,7 @@ impl Generator {
     pub(crate) fn builder_tags(
         &self,
         methods: &[OperationMethod],
+        tag_info: &BTreeMap<&String, &openapiv3::Tag>,
     ) -> (TokenStream, TokenStream) {
         let mut base = Vec::new();
         let mut ext = BTreeMap::new();
@@ -2055,6 +2056,10 @@ impl Generator {
         let (ext_impl, ext_use): (Vec<_>, Vec<_>) = ext
             .into_iter()
             .map(|(tag, trait_methods)| {
+                let desc = tag_info
+                    .get(&tag)
+                    .and_then(|tag| tag.description.as_ref())
+                    .map(|d| quote! { #[doc = #d] });
                 let tr =
                     format_ident!("Client{}Ext", sanitize(&tag, Case::Pascal));
                 let (trait_methods, trait_impls): (
@@ -2063,6 +2068,7 @@ impl Generator {
                 ) = trait_methods.into_iter().unzip();
                 (
                     quote! {
+                        #desc
                         pub trait #tr {
                             #(#trait_methods)*
                         }
diff --git a/progenitor-impl/tests/output/buildomat-builder-tagged.out b/progenitor-impl/tests/output/buildomat-builder-tagged.out
index 324c81a..a195db9 100644
--- a/progenitor-impl/tests/output/buildomat-builder-tagged.out
+++ b/progenitor-impl/tests/output/buildomat-builder-tagged.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -2344,6 +2345,7 @@ impl Client {
     }
 }
 
+/// Types for composing operation parameters.
 pub mod builder {
     use super::types;
     #[allow(unused_imports)]
@@ -3346,6 +3348,8 @@ pub mod builder {
     }
 }
 
+/// Items consumers will typically use such as the Client and
+/// extension traits.
 pub mod prelude {
     pub use super::Client;
 }
diff --git a/progenitor-impl/tests/output/buildomat-builder.out b/progenitor-impl/tests/output/buildomat-builder.out
index 2e52a83..48b685f 100644
--- a/progenitor-impl/tests/output/buildomat-builder.out
+++ b/progenitor-impl/tests/output/buildomat-builder.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -2344,6 +2345,7 @@ impl Client {
     }
 }
 
+/// Types for composing operation parameters.
 pub mod builder {
     use super::types;
     #[allow(unused_imports)]
@@ -3346,6 +3348,7 @@ pub mod builder {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use self::super::Client;
 }
diff --git a/progenitor-impl/tests/output/buildomat-positional.out b/progenitor-impl/tests/output/buildomat-positional.out
index 981d900..c14f741 100644
--- a/progenitor-impl/tests/output/buildomat-positional.out
+++ b/progenitor-impl/tests/output/buildomat-positional.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -1205,6 +1206,7 @@ impl Client {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use super::Client;
 }
diff --git a/progenitor-impl/tests/output/keeper-builder-tagged.out b/progenitor-impl/tests/output/keeper-builder-tagged.out
index f24797e..143897a 100644
--- a/progenitor-impl/tests/output/keeper-builder-tagged.out
+++ b/progenitor-impl/tests/output/keeper-builder-tagged.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -1332,6 +1333,7 @@ impl Client {
     }
 }
 
+/// Types for composing operation parameters.
 pub mod builder {
     use super::types;
     #[allow(unused_imports)]
@@ -1777,6 +1779,8 @@ pub mod builder {
     }
 }
 
+/// Items consumers will typically use such as the Client and
+/// extension traits.
 pub mod prelude {
     pub use super::Client;
 }
diff --git a/progenitor-impl/tests/output/keeper-builder.out b/progenitor-impl/tests/output/keeper-builder.out
index ea9f176..6b27f06 100644
--- a/progenitor-impl/tests/output/keeper-builder.out
+++ b/progenitor-impl/tests/output/keeper-builder.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -1332,6 +1333,7 @@ impl Client {
     }
 }
 
+/// Types for composing operation parameters.
 pub mod builder {
     use super::types;
     #[allow(unused_imports)]
@@ -1777,6 +1779,7 @@ pub mod builder {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use self::super::Client;
 }
diff --git a/progenitor-impl/tests/output/keeper-positional.out b/progenitor-impl/tests/output/keeper-positional.out
index 216e6ed..2662470 100644
--- a/progenitor-impl/tests/output/keeper-positional.out
+++ b/progenitor-impl/tests/output/keeper-positional.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -655,6 +656,7 @@ impl Client {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use super::Client;
 }
diff --git a/progenitor-impl/tests/output/nexus-builder-tagged.out b/progenitor-impl/tests/output/nexus-builder-tagged.out
index 107ca3b..0cc90f2 100644
--- a/progenitor-impl/tests/output/nexus-builder-tagged.out
+++ b/progenitor-impl/tests/output/nexus-builder-tagged.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -24534,6 +24535,8 @@ impl Client {
     }
 }
 
+///Virtual disks are used to store instance-local data which includes the
+/// operating system.
 pub trait ClientDisksExt {
     ///Fetch a disk by id
     ///
@@ -24758,6 +24761,7 @@ impl ClientDisksExt for Client {
     }
 }
 
+///TODO operations that will not ship to customers
 pub trait ClientHiddenExt {
     ///Start an OAuth 2.0 Device Authorization Grant
     ///
@@ -24881,6 +24885,7 @@ impl ClientHiddenExt for Client {
     }
 }
 
+///Images are read-only Virtual Disks that may be used to boot Virtual Machines
 pub trait ClientImagesExt {
     ///Fetch an image by id
     ///
@@ -24999,6 +25004,8 @@ impl ClientImagesExt for Client {
     }
 }
 
+///Virtual machine instances are the basic unit of computation. These
+/// operations are used for provisioning, controlling, and destroying instances.
 pub trait ClientInstancesExt {
     ///Fetch an instance by id
     ///
@@ -25744,6 +25751,7 @@ impl ClientInstancesExt for Client {
     }
 }
 
+///Authentication endpoints
 pub trait ClientLoginExt {
     ///Authenticate a user (i.e., log in) via username and password
     ///
@@ -25801,6 +25809,9 @@ impl ClientLoginExt for Client {
     }
 }
 
+///Metrics provide insight into the operation of the Oxide deployment. These
+/// include telemetry on hardware and software components that can be used to
+/// understand the current state as well as to diagnose issues.
 pub trait ClientMetricsExt {
     ///List timeseries schema
     ///
@@ -25826,6 +25837,8 @@ impl ClientMetricsExt for Client {
     }
 }
 
+///Organizations represent a subset of users and projects in an Oxide
+/// deployment.
 pub trait ClientOrganizationsExt {
     ///Fetch an organization by id
     ///
@@ -26102,6 +26115,7 @@ impl ClientOrganizationsExt for Client {
     }
 }
 
+///System-wide IAM policy
 pub trait ClientPolicyExt {
     ///Fetch the top-level IAM policy
     ///
@@ -26136,6 +26150,8 @@ impl ClientPolicyExt for Client {
     }
 }
 
+///Projects are a grouping of associated resources such as instances and disks
+/// within an organization for purposes of billing and access control.
 pub trait ClientProjectsExt {
     ///Fetch a project by id
     ///
@@ -26439,6 +26455,8 @@ impl ClientProjectsExt for Client {
     }
 }
 
+///Roles are a component of Identity and Access Management (IAM) that allow a
+/// user or agent account access to additional permissions.
 pub trait ClientRolesExt {
     ///List built-in roles
     ///
@@ -26481,6 +26499,7 @@ impl ClientRolesExt for Client {
     }
 }
 
+///Information pertaining to the current session.
 pub trait ClientSessionExt {
     ///List SSH public keys
     ///
@@ -26563,6 +26582,7 @@ impl ClientSessionExt for Client {
     }
 }
 
+///Silos represent a logical partition of users and resources.
 pub trait ClientSilosExt {
     ///List groups
     ///
@@ -26641,6 +26661,7 @@ impl ClientSilosExt for Client {
     }
 }
 
+///Snapshots of Virtual Disks at a particular point in time.
 pub trait ClientSnapshotsExt {
     ///Fetch a snapshot by id
     ///
@@ -26750,6 +26771,7 @@ impl ClientSnapshotsExt for Client {
     }
 }
 
+///Internal system information
 pub trait ClientSystemExt {
     ///Fetch a system-wide image by id
     ///
@@ -27852,6 +27874,8 @@ impl ClientSystemExt for Client {
     }
 }
 
+///A Virtual Private Cloud (VPC) is an isolated network environment that should
+/// probaby be moved into a more generic networking tag
 pub trait ClientVpcsExt {
     ///Fetch a route by id
     ///
@@ -28436,6 +28460,7 @@ impl ClientVpcsExt for Client {
     }
 }
 
+/// Types for composing operation parameters.
 pub mod builder {
     use super::types;
     #[allow(unused_imports)]
@@ -48624,6 +48649,8 @@ pub mod builder {
     }
 }
 
+/// Items consumers will typically use such as the Client and
+/// extension traits.
 pub mod prelude {
     pub use super::Client;
     pub use super::ClientDisksExt;
diff --git a/progenitor-impl/tests/output/nexus-builder.out b/progenitor-impl/tests/output/nexus-builder.out
index 7bad130..e48c617 100644
--- a/progenitor-impl/tests/output/nexus-builder.out
+++ b/progenitor-impl/tests/output/nexus-builder.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -28540,6 +28541,7 @@ impl Client {
     }
 }
 
+/// Types for composing operation parameters.
 pub mod builder {
     use super::types;
     #[allow(unused_imports)]
@@ -48727,6 +48729,7 @@ pub mod builder {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use self::super::Client;
 }
diff --git a/progenitor-impl/tests/output/nexus-positional.out b/progenitor-impl/tests/output/nexus-positional.out
index 9d47fc8..673331d 100644
--- a/progenitor-impl/tests/output/nexus-positional.out
+++ b/progenitor-impl/tests/output/nexus-positional.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -23861,6 +23862,7 @@ impl Client {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use super::Client;
 }
diff --git a/progenitor-impl/tests/output/param-collision-builder-tagged.out b/progenitor-impl/tests/output/param-collision-builder-tagged.out
index 4de691e..6483b4b 100644
--- a/progenitor-impl/tests/output/param-collision-builder-tagged.out
+++ b/progenitor-impl/tests/output/param-collision-builder-tagged.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -99,6 +100,7 @@ impl Client {
     }
 }
 
+/// Types for composing operation parameters.
 pub mod builder {
     use super::types;
     #[allow(unused_imports)]
@@ -231,6 +233,8 @@ pub mod builder {
     }
 }
 
+/// Items consumers will typically use such as the Client and
+/// extension traits.
 pub mod prelude {
     pub use super::Client;
 }
diff --git a/progenitor-impl/tests/output/param-collision-builder.out b/progenitor-impl/tests/output/param-collision-builder.out
index 5efd0dc..bac364c 100644
--- a/progenitor-impl/tests/output/param-collision-builder.out
+++ b/progenitor-impl/tests/output/param-collision-builder.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -99,6 +100,7 @@ impl Client {
     }
 }
 
+/// Types for composing operation parameters.
 pub mod builder {
     use super::types;
     #[allow(unused_imports)]
@@ -231,6 +233,7 @@ pub mod builder {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use self::super::Client;
 }
diff --git a/progenitor-impl/tests/output/param-collision-positional.out b/progenitor-impl/tests/output/param-collision-positional.out
index 8b40af6..aa439b0 100644
--- a/progenitor-impl/tests/output/param-collision-positional.out
+++ b/progenitor-impl/tests/output/param-collision-positional.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -109,6 +110,7 @@ impl Client {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use super::Client;
 }
diff --git a/progenitor-impl/tests/output/param-overrides-builder-tagged.out b/progenitor-impl/tests/output/param-overrides-builder-tagged.out
index 71d12a3..d6fff49 100644
--- a/progenitor-impl/tests/output/param-overrides-builder-tagged.out
+++ b/progenitor-impl/tests/output/param-overrides-builder-tagged.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -93,6 +94,7 @@ impl Client {
     }
 }
 
+/// Types for composing operation parameters.
 pub mod builder {
     use super::types;
     #[allow(unused_imports)]
@@ -168,6 +170,8 @@ pub mod builder {
     }
 }
 
+/// Items consumers will typically use such as the Client and
+/// extension traits.
 pub mod prelude {
     pub use super::Client;
 }
diff --git a/progenitor-impl/tests/output/param-overrides-builder.out b/progenitor-impl/tests/output/param-overrides-builder.out
index d0c638f..6c96c23 100644
--- a/progenitor-impl/tests/output/param-overrides-builder.out
+++ b/progenitor-impl/tests/output/param-overrides-builder.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -93,6 +94,7 @@ impl Client {
     }
 }
 
+/// Types for composing operation parameters.
 pub mod builder {
     use super::types;
     #[allow(unused_imports)]
@@ -168,6 +170,7 @@ pub mod builder {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use self::super::Client;
 }
diff --git a/progenitor-impl/tests/output/param-overrides-positional.out b/progenitor-impl/tests/output/param-overrides-positional.out
index 05610f4..8ae5923 100644
--- a/progenitor-impl/tests/output/param-overrides-positional.out
+++ b/progenitor-impl/tests/output/param-overrides-positional.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -106,6 +107,7 @@ impl Client {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use super::Client;
 }
diff --git a/progenitor-impl/tests/output/propolis-server-builder-tagged.out b/progenitor-impl/tests/output/propolis-server-builder-tagged.out
index 3a97665..38c7dbd 100644
--- a/progenitor-impl/tests/output/propolis-server-builder-tagged.out
+++ b/progenitor-impl/tests/output/propolis-server-builder-tagged.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -2888,6 +2889,7 @@ impl Client {
     }
 }
 
+/// Types for composing operation parameters.
 pub mod builder {
     use super::types;
     #[allow(unused_imports)]
@@ -3344,6 +3346,8 @@ pub mod builder {
     }
 }
 
+/// Items consumers will typically use such as the Client and
+/// extension traits.
 pub mod prelude {
     pub use super::Client;
 }
diff --git a/progenitor-impl/tests/output/propolis-server-builder.out b/progenitor-impl/tests/output/propolis-server-builder.out
index 3eb17ea..22ebc07 100644
--- a/progenitor-impl/tests/output/propolis-server-builder.out
+++ b/progenitor-impl/tests/output/propolis-server-builder.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -2924,6 +2925,7 @@ impl Client {
     }
 }
 
+/// Types for composing operation parameters.
 pub mod builder {
     use super::types;
     #[allow(unused_imports)]
@@ -3380,6 +3382,7 @@ pub mod builder {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use self::super::Client;
 }
diff --git a/progenitor-impl/tests/output/propolis-server-positional.out b/progenitor-impl/tests/output/propolis-server-positional.out
index 487cc50..e520be9 100644
--- a/progenitor-impl/tests/output/propolis-server-positional.out
+++ b/progenitor-impl/tests/output/propolis-server-positional.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -1661,6 +1662,7 @@ impl Client {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use super::Client;
 }
diff --git a/progenitor-impl/tests/output/test_default_params_builder.out b/progenitor-impl/tests/output/test_default_params_builder.out
index 8153f5f..e6f5410 100644
--- a/progenitor-impl/tests/output/test_default_params_builder.out
+++ b/progenitor-impl/tests/output/test_default_params_builder.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -358,6 +359,7 @@ impl Client {
     }
 }
 
+/// Types for composing operation parameters.
 pub mod builder {
     use super::types;
     #[allow(unused_imports)]
@@ -421,6 +423,7 @@ pub mod builder {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use self::super::Client;
 }
diff --git a/progenitor-impl/tests/output/test_default_params_positional.out b/progenitor-impl/tests/output/test_default_params_positional.out
index 287f28a..298ed1c 100644
--- a/progenitor-impl/tests/output/test_default_params_positional.out
+++ b/progenitor-impl/tests/output/test_default_params_positional.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -191,6 +192,7 @@ impl Client {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use super::Client;
 }
diff --git a/progenitor-impl/tests/output/test_freeform_response.out b/progenitor-impl/tests/output/test_freeform_response.out
index 8b1d54c..c439a4b 100644
--- a/progenitor-impl/tests/output/test_freeform_response.out
+++ b/progenitor-impl/tests/output/test_freeform_response.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -124,6 +125,7 @@ impl Client {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use super::Client;
 }
diff --git a/progenitor-impl/tests/output/test_renamed_parameters.out b/progenitor-impl/tests/output/test_renamed_parameters.out
index 2cfb68b..541e7fb 100644
--- a/progenitor-impl/tests/output/test_renamed_parameters.out
+++ b/progenitor-impl/tests/output/test_renamed_parameters.out
@@ -3,6 +3,7 @@ use progenitor_client::{encode_path, RequestBuilderExt};
 pub use progenitor_client::{ByteStream, Error, ResponseValue};
 #[allow(unused_imports)]
 use reqwest::header::{HeaderMap, HeaderValue};
+/// Types used as operation parameters and responses.
 pub mod types {
     use serde::{Deserialize, Serialize};
     #[allow(unused_imports)]
@@ -154,6 +155,7 @@ impl Client {
     }
 }
 
+/// Items consumers will typically use such as the Client.
 pub mod prelude {
     pub use super::Client;
 }