Clean up some codegen, add ability to autogenerate generated crate de…

…scription

.github/workflows/async-stripe.yml

@@ -168,4 +168,4 @@ jobs:
       - uses: Swatinem/rust-cache@v2
 
       - name: Check examples
-        run: cargo clippy --features "runtime-tokio-hyper-rustls" --all
+        run: cargo clippy --features "runtime-tokio-hyper-rustls" --workspace

generated/stripe_billing/src/mod.rs

@@ -1,6 +1,10 @@
 #![recursion_limit = "256"]
 #![allow(clippy::large_enum_variant)]
 #![allow(rustdoc::invalid_html_tags)]
+
+//! This crate provides Rust bindings to the Stripe HTTP API, specifically
+//! for requests mentioned in the `Billing` section of the [Stripe API docs](https://stripe.com/docs/api)
+
 extern crate self as stripe_billing;
 pub use stripe_types::AutomaticTax;
 pub mod automatic_tax;

generated/stripe_checkout/src/mod.rs

@@ -1,6 +1,10 @@
 #![recursion_limit = "256"]
 #![allow(clippy::large_enum_variant)]
 #![allow(rustdoc::invalid_html_tags)]
+
+//! This crate provides Rust bindings to the Stripe HTTP API,
+//! centered around [Checkout Sessions](https://stripe.com/docs/api/checkout/sessions).
+
 extern crate self as stripe_checkout;
 pub mod checkout_session;
 pub use checkout_session::CheckoutSession;

generated/stripe_connect/src/mod.rs

@@ -1,6 +1,10 @@
 #![recursion_limit = "256"]
 #![allow(clippy::large_enum_variant)]
 #![allow(rustdoc::invalid_html_tags)]
+
+//! This crate provides Rust bindings to the Stripe HTTP API, specifically
+//! for requests mentioned in the `Connect` section of the [Stripe API docs](https://stripe.com/docs/api)
+
 extern crate self as stripe_connect;
 pub use stripe_types::Account;
 pub mod account;

generated/stripe_core/src/mod.rs

@@ -1,6 +1,10 @@
 #![recursion_limit = "256"]
 #![allow(clippy::large_enum_variant)]
 #![allow(rustdoc::invalid_html_tags)]
+
+//! This crate provides Rust bindings to the Stripe HTTP API, specifically
+//! for requests mentioned in the `Core Resources` section of the [Stripe API docs](https://stripe.com/docs/api)
+
 extern crate self as stripe_core;
 pub mod balance;
 pub use balance::Balance;

generated/stripe_fraud/src/mod.rs

@@ -1,6 +1,10 @@
 #![recursion_limit = "256"]
 #![allow(clippy::large_enum_variant)]
 #![allow(rustdoc::invalid_html_tags)]
+
+//! This crate provides Rust bindings to the Stripe HTTP API, specifically
+//! for requests mentioned in the `Fraud` section of the [Stripe API docs](https://stripe.com/docs/api)
+
 extern crate self as stripe_fraud;
 pub mod deleted_radar_value_list;
 pub use deleted_radar_value_list::DeletedRadarValueList;

generated/stripe_issuing/src/mod.rs

@@ -1,6 +1,10 @@
 #![recursion_limit = "256"]
 #![allow(clippy::large_enum_variant)]
 #![allow(rustdoc::invalid_html_tags)]
+
+//! This crate provides Rust bindings to the Stripe HTTP API, specifically
+//! for requests mentioned in the `Issuing` section of the [Stripe API docs](https://stripe.com/docs/api)
+
 extern crate self as stripe_issuing;
 pub use stripe_types::FundingInstructions;
 pub mod funding_instructions;

generated/stripe_misc/src/mod.rs

@@ -1,6 +1,11 @@
 #![recursion_limit = "256"]
 #![allow(clippy::large_enum_variant)]
 #![allow(rustdoc::invalid_html_tags)]
+
+//! This crate provides Rust bindings to the Stripe HTTP API, specifically
+//! for requests mentioned in the `Tax`, `Identity`, `Reporting`, `Sigma`, `Financial Connections`
+//! and `Webhooks` sections of the [Stripe API docs](https://stripe.com/docs/api)
+
 extern crate self as stripe_misc;
 pub mod apple_pay_domain;
 pub use apple_pay_domain::ApplePayDomain;

generated/stripe_payment/src/mod.rs

@@ -1,6 +1,11 @@
 #![recursion_limit = "256"]
 #![allow(clippy::large_enum_variant)]
 #![allow(rustdoc::invalid_html_tags)]
+
+//! This crate provides Rust bindings to the Stripe HTTP API, specifically
+//! for requests mentioned in the `Payment Methods` and `Payment Links` sections
+//! of the [Stripe API docs](https://stripe.com/docs/api)
+
 extern crate self as stripe_payment;
 pub use stripe_types::BankAccount;
 pub mod bank_account;

generated/stripe_product/src/mod.rs

@@ -1,6 +1,10 @@
 #![recursion_limit = "256"]
 #![allow(clippy::large_enum_variant)]
 #![allow(rustdoc::invalid_html_tags)]
+
+//! This crate provides Rust bindings to the Stripe HTTP API, specifically
+//! for requests mentioned in the `Products` section of the [Stripe API docs](https://stripe.com/docs/api)
+
 extern crate self as stripe_product;
 pub use stripe_types::Coupon;
 pub mod coupon;

generated/stripe_terminal/src/mod.rs

@@ -1,6 +1,10 @@
 #![recursion_limit = "256"]
 #![allow(clippy::large_enum_variant)]
 #![allow(rustdoc::invalid_html_tags)]
+
+//! This crate provides Rust bindings to the Stripe HTTP API, specifically
+//! for requests mentioned in the `Terminal` section of the [Stripe API docs](https://stripe.com/docs/api)
+
 extern crate self as stripe_terminal;
 pub mod deleted_terminal_configuration;
 pub use deleted_terminal_configuration::DeletedTerminalConfiguration;

generated/stripe_treasury/src/mod.rs

@@ -1,6 +1,10 @@
 #![recursion_limit = "256"]
 #![allow(clippy::large_enum_variant)]
 #![allow(rustdoc::invalid_html_tags)]
+
+//! This crate provides Rust bindings to the Stripe HTTP API, specifically
+//! for requests mentioned in the `Treasury` section of the [Stripe API docs](https://stripe.com/docs/api)
+
 extern crate self as stripe_treasury;
 pub mod inbound_transfers;
 pub use inbound_transfers::InboundTransfers;

openapi/gen_crates.toml

@@ -10,15 +10,24 @@ paths =  [
     "quote",
     "subscription"
 ]
+description = '''This crate provides Rust bindings to the Stripe HTTP API, specifically
+for requests mentioned in the `Billing` section of the [Stripe API docs](https://stripe.com/docs/api)
+'''
 
 [[crates]]
 name = "checkout"
 packages = ["checkout"]
+description = '''This crate provides Rust bindings to the Stripe HTTP API,
+centered around [Checkout Sessions](https://stripe.com/docs/api/checkout/sessions).
+'''
 
 [[crates]]
 name = "connect"
 paths = ["country_spec", "account", "topup", "application_fee", "transfer", "application"]
 packages = ["apps"]
+description = '''This crate provides Rust bindings to the Stripe HTTP API, specifically
+for requests mentioned in the `Connect` section of the [Stripe API docs](https://stripe.com/docs/api)
+'''
 
 [[crates]]
 name = "core"
@@ -38,16 +47,25 @@ paths = [
     "refund",
     "token"
 ]
+description = '''This crate provides Rust bindings to the Stripe HTTP API, specifically
+for requests mentioned in the `Core Resources` section of the [Stripe API docs](https://stripe.com/docs/api)
+'''
 
 [[crates]]
 name = "fraud"
 paths = ["review"]
 packages = ["radar"]
+description = '''This crate provides Rust bindings to the Stripe HTTP API, specifically
+for requests mentioned in the `Fraud` section of the [Stripe API docs](https://stripe.com/docs/api)
+'''
 
 [[crates]]
 name = "issuing"
 paths = ["funding_instructions"]
 packages = ["issuing"]
+description = '''This crate provides Rust bindings to the Stripe HTTP API, specifically
+for requests mentioned in the `Issuing` section of the [Stripe API docs](https://stripe.com/docs/api)
+'''
 
 [[crates]]
 name = "payment"
@@ -58,6 +76,10 @@ paths = [
     "bank_account",
     "payment_link"
 ]
+description = '''This crate provides Rust bindings to the Stripe HTTP API, specifically
+for requests mentioned in the `Payment Methods` and `Payment Links` sections
+of the [Stripe API docs](https://stripe.com/docs/api)
+'''
 
 [[crates]]
 name = "product"
@@ -71,27 +93,23 @@ paths = [
     "tax_rate",
     "shipping_rate"
 ]
+description = '''This crate provides Rust bindings to the Stripe HTTP API, specifically
+for requests mentioned in the `Products` section of the [Stripe API docs](https://stripe.com/docs/api)
+'''
 
 [[crates]]
 name = "terminal"
 packages = ["terminal"]
+description = '''This crate provides Rust bindings to the Stripe HTTP API, specifically
+for requests mentioned in the `Terminal` section of the [Stripe API docs](https://stripe.com/docs/api)
+'''
 
 [[crates]]
 name = "treasury"
 packages = ["treasury"]
-
-[[crates]]
-name = "types"
-paths = [
-    "api_errors",
-    "shipping",
-    "address",
-
-    # These should not need to be manually specified, but currently
-    # cannot have their crate inferred
-    "linked_account_options_us_bank_account",
-    "radar_radar_options"
-]
+description = '''This crate provides Rust bindings to the Stripe HTTP API, specifically
+for requests mentioned in the `Treasury` section of the [Stripe API docs](https://stripe.com/docs/api)
+'''
 
 [[crates]]
 name = "misc"
@@ -107,4 +125,22 @@ packages = [
     "reporting",
     "sigma",
     "financial_connections"
-]
+]
+description = '''This crate provides Rust bindings to the Stripe HTTP API, specifically
+for requests mentioned in the `Tax`, `Identity`, `Reporting`, `Sigma`, `Financial Connections`
+and `Webhooks` sections of the [Stripe API docs](https://stripe.com/docs/api)
+'''
+
+[[crates]]
+name = "types"
+paths = [
+    "api_errors",
+    "shipping",
+    "address",
+
+    # These should not need to be manually specified, but currently
+    # cannot have their crate inferred
+    "linked_account_options_us_bank_account",
+    "radar_radar_options"
+]
+

openapi/src/codegen.rs

@@ -6,29 +6,36 @@ use indoc::formatdoc;
 use tracing::debug;
 
 use crate::components::{get_components, Components};
-use crate::crate_inference::{Crate, ALL_CRATES};
+use crate::crate_inference::{get_crate_doc_comment, Crate, ALL_CRATES};
 use crate::crate_table::write_crate_table;
 use crate::object_writing::{gen_obj, gen_requests, ObjectGenInfo};
 use crate::rust_object::ObjectMetadata;
 use crate::spec::Spec;
 use crate::spec_inference::infer_doc_comment;
 use crate::stripe_object::StripeObject;
 use crate::templates::cargo_toml::gen_crate_toml;
+use crate::templates::utils::write_top_level_doc_comment;
 use crate::url_finder::UrlFinder;
 use crate::utils::{append_to_file, write_to_file};
 use crate::webhook::write_generated_for_webhooks;
 
 pub struct CodeGen {
     pub components: Components,
     pub spec: Spec,
-    pub url_finder: UrlFinder,
 }
 
 impl CodeGen {
     pub fn new(spec: Spec, url_finder: UrlFinder) -> anyhow::Result<Self> {
-        let components = get_components(&spec)?;
+        let mut components = get_components(&spec)?;
 
-        Ok(Self { components, spec, url_finder })
+        // Attach doc urls for top-level components
+        for comp in components.components.values_mut() {
+            if let Some(doc_url) = url_finder.url_for_object(comp.path()) {
+                comp.stripe_doc_url = Some(doc_url);
+            }
+        }
+
+        Ok(Self { components, spec })
     }
 
     fn write_generated_for_types_crate(&self) -> anyhow::Result<()> {
@@ -130,6 +137,9 @@ impl CodeGen {
                 write_to_file(toml, base_path.join("Cargo.toml"))?;
 
                 let crate_name = krate.name();
+                let doc_comment = write_top_level_doc_comment(
+                    &get_crate_doc_comment(*krate).expect("No doc comment for crate"),
+                );
 
                 // We set up some things in the base `mod.rs` file:
                 // 1. Without this recursion limit increase, `cargo doc` fails
@@ -140,6 +150,8 @@ impl CodeGen {
             #![recursion_limit = "256"]
             #![allow(clippy::large_enum_variant)]
             #![allow(rustdoc::invalid_html_tags)]
+            
+            {doc_comment}
             extern crate self as {crate_name};
             "#
                 };
@@ -172,9 +184,8 @@ impl CodeGen {
 
     fn gen_struct_definitions_for_component(&self, comp: &StripeObject) -> String {
         let base_obj = comp.rust_obj();
-        let doc_url = self.url_finder.url_for_object(comp.path());
         let schema = self.spec.get_component_schema(comp.path());
-        let doc_comment = infer_doc_comment(schema, doc_url.as_deref());
+        let doc_comment = infer_doc_comment(schema, comp.stripe_doc_url.as_deref());
         let meta =
             ObjectMetadata::new(comp.ident().clone(), ObjectGenInfo::new_deser()).doc(doc_comment);
 

openapi/src/components.rs

@@ -269,7 +269,7 @@ pub fn get_components(spec: &Spec) -> anyhow::Result<Components> {
                 resource: resource.clone(),
                 data,
                 krate: inferred_krate.map(CrateInfo::new),
-                extra_types: Default::default(),
+                stripe_doc_url: None,
             },
         );
     }