Clean up API docstrings, remove "IPv6 unsupported" (#9562)

At the moment, some docstrings in the generated docs lack newlines, and
string together multiple sentences without punctuation. For example, the
`provisioned` field in the `silo_utilization_list` method is a bit
garbled: https://docs.oxide.computer/api/silo_utilization_list.

> Accounts for resources allocated by in silos like CPU or memory for
running
> instances and storage for disks and snapshots Note that CPU and memory
> resources associated with a stopped instances are not counted here

This patch adds the missing newlines and punctuation to make this
docstring readable. Note that these changes won't show up in the
generated docs until we cut a new release.

Note: if this change makes sense, I'll also ask Claude to review all
docstrings in this crate for similar issues.

cc @david-crespo in case this is relevant to your interests (docs style
guide, making Claude do things).

---------

Co-authored-by: David Crespo <david.crespo@oxidecomputer.com>

Author: jmcarp

.claude/skills/api-docs-lint/SKILL.md

@@ -0,0 +1,133 @@
+# API Docstring Style Guide
+
+This guide covers public docstrings (`///`) on endpoint handlers in
+`nexus/external-api/src/lib.rs` and 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
+
+Short, label-like descriptions do not need periods. This includes endpoint
+summary lines, struct-level descriptions, and brief field annotations. Longer
+explanatory text (especially multi-clause or multi-sentence docstrings) should
+end sentences with periods.
+
+```rust
+// Endpoint summary lines: no period
+/// Fetch silo
+/// List identity providers for silo
+/// Create IP pool
+
+// Struct-level descriptions: no period
+/// View of a Silo
+/// A collection of resource counts used to describe capacity and utilization
+
+// Short field descriptions: no period
+/// Number of virtual CPUs
+/// Common identifying metadata
+/// Size of blocks in bytes
+
+// Longer explanatory text: use periods
+/// Accounts for resources allocated to running instances or storage
+/// allocated via disks or snapshots.
+///
+/// Note that CPU and memory resources associated with stopped instances
+/// are not counted here, whereas associated disks will still be counted.
+```
+
+## Articles
+
+Omit articles ("a", "an", "the") in endpoint summary lines. Look at existing
+endpoints in `nexus/external-api/src/lib.rs` for reference. A few examples of
+the different shapes:
+
+```rust
+// Bad
+/// Fetch a silo
+/// Create an IP pool
+/// Delete the project
+/// List the silos
+
+// Good
+/// Fetch silo
+/// Create IP pool
+/// Delete project
+/// List silos
+/// Fetch resource utilization for user's current silo
+/// List identity providers for silo
+/// Add range to IP pool
+```
+
+## 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", "DER"
+
+## 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:
+- Endpoint handler docstrings (`/// Fetch silo`)
+- 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: correct articles ("a" vs "an"),
+subject-verb agreement, proper spelling, etc.

nexus/external-api/src/lib.rs

@@ -79,6 +79,7 @@ api_versions!([
     // |  date-based version should be at the top of the list.
     // v
     // (next_yyyymmddnn, IDENT),
+    (2026021300, STALE_DOCS_AND_PUNCTUATION),
     (2026020901, UPDATE_EXTERNAL_SUBNET_DOCS),
     (2026020900, RENAME_POOL_ENDPOINTS),
     (2026020600, ADD_SILO_SUBNET_POOLS),
@@ -1152,8 +1153,6 @@ pub trait NexusExternalApi {
     ) -> Result<HttpResponseOk<ResultsPage<views::IpPool>>, HttpError>;
 
     /// Create IP pool
-    ///
-    /// IPv6 is not yet supported for unicast pools.
     #[endpoint {
         operation_id = "ip_pool_create",
         method = POST,
@@ -1169,8 +1168,6 @@ pub trait NexusExternalApi {
     }
 
     /// Create IP pool
-    ///
-    /// IPv6 is not yet supported for unicast pools.
     #[endpoint {
         method = POST,
         path = "/v1/system/ip-pools",
@@ -1502,8 +1499,6 @@ pub trait NexusExternalApi {
 
     /// Add range to IP pool
     ///
-    /// IPv6 ranges are not allowed yet for unicast pools.
-    ///
     /// For multicast pools, all ranges must be either Any-Source Multicast (ASM)
     /// or Source-Specific Multicast (SSM), but not both. Mixing ASM and SSM
     /// ranges in the same pool is not allowed.
@@ -1527,8 +1522,6 @@ pub trait NexusExternalApi {
 
     /// Add range to IP pool
     ///
-    /// IPv6 ranges are not allowed yet for unicast pools.
-    ///
     /// For multicast pools, all ranges must be either Any-Source Multicast (ASM)
     /// or Source-Specific Multicast (SSM), but not both. Mixing ASM and SSM
     /// ranges in the same pool is not allowed.

nexus/types/src/external_api/params.rs

@@ -242,7 +242,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
@@ -693,9 +693,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,
 }
 
@@ -792,11 +792,12 @@ 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,
 }
@@ -916,25 +917,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>,
@@ -1398,7 +1399,7 @@ impl PrivateIpStackCreate {
 /// 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
@@ -1946,7 +1947,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>,
 
@@ -2317,7 +2318,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()),
@@ -2356,7 +2357,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,
     },
 
@@ -2450,7 +2451,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 {
@@ -2482,6 +2483,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,
 }
@@ -2831,7 +2833,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 {
@@ -3011,7 +3013,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,
 
@@ -3030,7 +3032,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

@@ -429,8 +429,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,