More docs lint.

Author: jmcarp

nexus/types/src/external_api/params.rs

@@ -207,7 +207,7 @@ pub struct SamlIdentityProviderSelector {
 
 // The shape of this selector is slightly different than the others given that
 // silos users can only be specified via ID and are automatically provided by
-// the environment the user is authetnicated in
+// the environment the user is authenticated in
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema, PartialEq)]
 pub struct SshKeySelector {
     /// ID of the silo user
@@ -542,9 +542,9 @@ pub struct SiloAuthSettingsUpdate {
 /// Create-time parameters for a `User`
 #[derive(Clone, Deserialize, JsonSchema)]
 pub struct UserCreate {
-    /// username used to log in
+    /// Username used to log in
     pub external_id: UserId,
-    /// how to set the user's login password
+    /// How to set the user's login password
     pub password: UserPassword,
 }
 
@@ -641,11 +641,11 @@ pub struct UsernamePasswordCredentials {
 
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct DerEncodedKeyPair {
-    /// request signing public certificate (base64 encoded der file)
+    /// Request signing public certificate (base64 encoded DER file)
     #[serde(deserialize_with = "x509_cert_from_base64_encoded_der")]
     pub public_cert: String,
 
-    /// request signing RSA private key in PKCS#1 format (base64 encoded der file)
+    /// Request signing RSA private key in PKCS#1 format (base64 encoded DER file)
     #[serde(deserialize_with = "key_from_base64_encoded_der")]
     pub private_key: String,
 }
@@ -765,25 +765,25 @@ pub struct SamlIdentityProviderCreate {
     #[serde(flatten)]
     pub identity: IdentityMetadataCreateParams,
 
-    /// the source of an identity provider metadata descriptor
+    /// The source of an identity provider metadata descriptor.
     pub idp_metadata_source: IdpMetadataSource,
 
-    /// idp's entity id
+    /// IdP's entity ID.
     pub idp_entity_id: String,
 
-    /// sp's client id
+    /// SP's client ID.
     pub sp_client_id: String,
 
-    /// service provider endpoint where the response will be sent
+    /// Service provider endpoint where the response will be sent.
     pub acs_url: String,
 
-    /// service provider endpoint where the idp should send log out requests
+    /// Service provider endpoint where the IdP should send log out requests.
     pub slo_url: String,
 
-    /// customer's technical contact for saml configuration
+    /// Customer's technical contact for SAML configuration.
     pub technical_contact_email: String,
 
-    /// request signing key pair
+    /// Request signing key pair.
     #[serde(default)]
     #[serde(deserialize_with = "validate_key_pair")]
     pub signing_keypair: Option<DerEncodedKeyPair>,
@@ -992,7 +992,7 @@ pub struct InstanceNetworkInterfaceUpdate {
 /// Create-time parameters for a `Certificate`
 #[derive(Clone, Deserialize, Serialize, JsonSchema)]
 pub struct CertificateCreate {
-    /// common identifying metadata
+    /// Common identifying metadata
     #[serde(flatten)]
     pub identity: IdentityMetadataCreateParams,
     /// PEM-formatted string containing public certificate chain
@@ -1328,7 +1328,7 @@ pub struct InstanceCreate {
     #[serde(default)]
     pub auto_restart_policy: Option<InstanceAutoRestartPolicy>,
 
-    /// Anti-Affinity groups which this instance should be added.
+    /// Anti-affinity groups to which this instance should be added.
     #[serde(default)]
     pub anti_affinity_groups: Vec<NameOrId>,
 
@@ -1694,7 +1694,7 @@ impl JsonSchema for BlockSize {
         schemars::schema::Schema::Object(schemars::schema::SchemaObject {
             metadata: Some(Box::new(schemars::schema::Metadata {
                 id: None,
-                title: Some("disk block size in bytes".to_string()),
+                title: Some("Disk block size in bytes".to_string()),
                 ..Default::default()
             })),
             instance_type: Some(schemars::schema::InstanceType::Integer.into()),
@@ -1733,7 +1733,7 @@ impl From<DiskVariant> for PhysicalDiskKind {
 pub enum DiskSource {
     /// Create a blank disk
     Blank {
-        /// size of blocks for this Disk. valid values are: 512, 2048, or 4096
+        /// Size of blocks for this disk. Valid values are: 512, 2048, or 4096.
         block_size: BlockSize,
     },
 
@@ -1817,7 +1817,7 @@ pub struct AddressLotCreate {
     pub blocks: Vec<AddressLotBlockCreate>,
 }
 
-/// Parameters for creating an address lot block. Fist and last addresses are
+/// Parameters for creating an address lot block. First and last addresses are
 /// inclusive.
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct AddressLotBlockCreate {
@@ -1849,6 +1849,7 @@ pub struct LoopbackAddressCreate {
     pub mask: u8,
 
     /// Address is an anycast address.
+    ///
     /// This allows the address to be assigned to multiple locations simultaneously.
     pub anycast: bool,
 }
@@ -2198,7 +2199,7 @@ pub struct BgpAnnouncementCreate {
     pub network: IpNet,
 }
 
-/// Parameters for creating a BGP configuration. This includes and autonomous
+/// Parameters for creating a BGP configuration. This includes an autonomous
 /// system number (ASN) and a virtual routing and forwarding (VRF) identifier.
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct BgpConfigCreate {
@@ -2378,7 +2379,7 @@ pub struct Distribution {
 /// Create-time parameters for an `Image`
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ImageCreate {
-    /// common identifying metadata
+    /// Common identifying metadata
     #[serde(flatten)]
     pub identity: IdentityMetadataCreateParams,
 
@@ -2397,7 +2398,7 @@ pub struct ImageCreate {
 /// Create-time parameters for a `Snapshot`
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct SnapshotCreate {
-    /// common identifying metadata
+    /// Common identifying metadata
     #[serde(flatten)]
     pub identity: IdentityMetadataCreateParams,
 

nexus/types/src/external_api/shared.rs

@@ -422,8 +422,9 @@ pub struct BfdStatus {
     pub mode: BfdMode,
 }
 
-/// Opaque object representing link state. The contents of this object are not
-/// yet stable.
+/// Opaque object representing link state.
+///
+/// The contents of this object are not yet stable.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub struct SwitchLinkState {
     link: serde_json::Value,

nexus/types/src/external_api/views.rs

@@ -294,10 +294,10 @@ pub struct Vpc {
     #[serde(flatten)]
     pub identity: IdentityMetadata,
 
-    /// id for the project containing this VPC
+    /// ID for the project containing this VPC
     pub project_id: Uuid,
 
-    /// id for the system router where subnet default routes are registered
+    /// ID for the system router where subnet default routes are registered
     pub system_router_id: Uuid,
 
     /// The unique local IPv6 address range for subnets in this VPC
@@ -312,7 +312,7 @@ pub struct Vpc {
 /// them, within an IPv4 subnetwork or optionally an IPv6 subnetwork.
 #[derive(ObjectIdentity, Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct VpcSubnet {
-    /// common identifying metadata
+    /// Common identifying metadata
     #[serde(flatten)]
     pub identity: IdentityMetadata,
 
@@ -340,7 +340,7 @@ pub enum VpcRouterKind {
 /// should be sent depending on its destination.
 #[derive(ObjectIdentity, Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct VpcRouter {
-    /// common identifying metadata
+    /// Common identifying metadata
     #[serde(flatten)]
     pub identity: IdentityMetadata,
 

prompts/openapi_lint.md

@@ -0,0 +1,97 @@
+# API Docstring Style Guide
+
+This guide covers public docstrings (`///` or `/** ... */`) on structs, fields,
+and enums in `nexus/types/src/external_api/`. These docstrings become user-facing
+API documentation.
+
+## Capitalization
+
+- Start all docstrings with a capital letter.
+
+```rust
+// Bad
+/// the source of an identity provider metadata descriptor
+pub idp_metadata_source: IdpMetadataSource,
+
+// Good
+/// The source of an identity provider metadata descriptor.
+pub idp_metadata_source: IdpMetadataSource,
+```
+
+## Punctuation
+
+- End all sentences with periods, including single-sentence docstrings.
+- Non-sentence fragments (e.g., short labels) do not need to end with periods.
+
+```rust
+// Bad
+/// The IP address held by this resource
+pub ip: IpAddr,
+
+// Good
+/// The IP address held by this resource.
+pub ip: IpAddr,
+
+// Also acceptable - fragment, not a sentence
+/// Common identifying metadata
+pub identity: IdentityMetadata,
+```
+
+## Paragraph Separation
+
+- Separate distinct thoughts or notes with a blank `///` line. This produces
+proper paragraph breaks in rendered documentation.
+
+```rust
+// Bad - renders as one run-on paragraph
+/// A unique, immutable, system-controlled identifier for the token.
+/// Note that this ID is not the bearer token itself, which starts with
+/// "oxide-token-".
+pub id: Uuid,
+
+// Good - renders as two paragraphs
+/// A unique, immutable, system-controlled identifier for the token.
+///
+/// Note that this ID is not the bearer token itself, which starts with
+/// "oxide-token-".
+pub id: Uuid,
+```
+
+## Acronyms and Abbreviations
+
+- Use standard casing for acronyms:
+  - "IdP" (Identity Provider)
+  - "SP" (Service Provider)
+  - "SAML", "ID", "IP", "VPC", "CPU", "RAM"
+
+## Doc Comments vs Regular Comments
+
+- Use `///` for public API documentation that users will see.
+- Use `//` for internal implementation notes that should not appear in generated
+docs.
+
+```rust
+// Bad - this won't appear in API docs
+// A list containing the IDs of the secret keys.
+pub secrets: Vec<WebhookSecret>,
+
+// Good - this will appear in API docs
+/// A list containing the IDs of the secret keys.
+pub secrets: Vec<WebhookSecret>,
+```
+
+## Scope
+
+These rules apply to:
+- Public struct docstrings (`/// View of a Silo`)
+- Public field docstrings (`/// The IP address held by this resource.`)
+- Public enum variant docstrings (`/// The sled is currently active.`)
+
+These rules do NOT apply to:
+- Private functions or structs
+- Internal comments (`//`)
+- Module-level documentation (`//!`)
+
+## General
+
+- Follow standard English grammatical rules.