add docs to mods and extension traits (#677)

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

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)*
                         }

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

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

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

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

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

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

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;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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