ryan
/
progenitor
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

add docs to mods and extension traits (#677)

This commit is contained in:
Adam Leventhal 2024-01-06 01:01:12 -08:00 committed by GitHub
parent e2f1f7cce0
commit 8088f55470
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
24 changed files with 110 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
progenitor-impl/src/lib.rs
View File

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

8
progenitor-impl/src/method.rs
View File

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

4
progenitor-impl/tests/output/buildomat-builder-tagged.out
View File

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

3
progenitor-impl/tests/output/buildomat-builder.out
View File

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

2
progenitor-impl/tests/output/buildomat-positional.out
View File

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

4
progenitor-impl/tests/output/keeper-builder-tagged.out
View File

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

3
progenitor-impl/tests/output/keeper-builder.out
View File

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

2
progenitor-impl/tests/output/keeper-positional.out
View File

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

27
progenitor-impl/tests/output/nexus-builder-tagged.out
View File

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

3
progenitor-impl/tests/output/nexus-builder.out
View File

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

2
progenitor-impl/tests/output/nexus-positional.out
View File

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

4
progenitor-impl/tests/output/param-collision-builder-tagged.out
View File

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

3
progenitor-impl/tests/output/param-collision-builder.out
View File

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

2
progenitor-impl/tests/output/param-collision-positional.out
View File

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

4
progenitor-impl/tests/output/param-overrides-builder-tagged.out
View File

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

3
progenitor-impl/tests/output/param-overrides-builder.out
View File

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

2
progenitor-impl/tests/output/param-overrides-positional.out
View File

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

4
progenitor-impl/tests/output/propolis-server-builder-tagged.out
View File

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

3
progenitor-impl/tests/output/propolis-server-builder.out
View File

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

2
progenitor-impl/tests/output/propolis-server-positional.out
View File

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

3
progenitor-impl/tests/output/test_default_params_builder.out
View File

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

2
progenitor-impl/tests/output/test_default_params_positional.out
View File

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

2
progenitor-impl/tests/output/test_freeform_response.out
View File

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

2
progenitor-impl/tests/output/test_renamed_parameters.out
View File

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