touch up some doc comments

oxidecomputer · Sep 18, 2024 · 7ef5e19 · 7ef5e19
1 parent f45e3b8
commit 7ef5e19
Show file tree

Hide file tree

Showing 3 changed files with 23 additions and 1 deletion.
diff --git a/bin/propolis-server/src/lib/migrate/compat.rs b/bin/propolis-server/src/lib/migrate/compat.rs
@@ -2,7 +2,8 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
-//! Checks for compatibility of two instance specs.
+//! Associated functions for the [`crate::spec::Spec`] type that determine
+//! whether two specs describe migration-compatible VMs.
 
 use std::collections::HashMap;
 

diff --git a/crates/propolis-api-types/src/instance_spec/components/devices.rs b/crates/propolis-api-types/src/instance_spec/components/devices.rs
@@ -108,13 +108,21 @@ pub struct QemuPvpanic {
 // Structs for Falcon devices. These devices don't support live migration.
 //
 
+/// Describes a SoftNPU PCI device.
+///
+/// This is only supported by Propolis servers compiled with the `falcon`
+/// feature.
 #[derive(Clone, Deserialize, Serialize, Debug, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct SoftNpuPciPort {
     /// The PCI path at which to attach the guest to this port.
     pub pci_path: PciPath,
 }
 
+/// Describes a SoftNPU network port.
+///
+/// This is only supported by Propolis servers compiled with the `falcon`
+/// feature.
 #[derive(Clone, Deserialize, Serialize, Debug, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct SoftNpuPort {
@@ -125,13 +133,22 @@ pub struct SoftNpuPort {
     pub backend_name: String,
 }
 
+/// Describes a PCI device that shares host files with the guest using the P9
+/// protocol.
+///
+/// This is only supported by Propolis servers compiled with the `falcon`
+/// feature.
 #[derive(Clone, Deserialize, Serialize, Debug, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct SoftNpuP9 {
     /// The PCI path at which to attach the guest to this port.
     pub pci_path: PciPath,
 }
 
+/// Describes a filesystem to expose through a P9 device.
+///
+/// This is only supported by Propolis servers compiled with the `falcon`
+/// feature.
 #[derive(Clone, Deserialize, Serialize, Debug, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct P9fs {

diff --git a/openapi/propolis-server.json b/openapi/propolis-server.json
@@ -1553,6 +1553,7 @@
         "additionalProperties": false
       },
       "P9fs": {
+        "description": "Describes a filesystem to expose through a P9 device.\n\nThis is only supported by Propolis servers compiled with the `falcon` feature.",
         "type": "object",
         "properties": {
           "chunk_size": {
@@ -1695,6 +1696,7 @@
         "minimum": 0
       },
       "SoftNpuP9": {
+        "description": "Describes a PCI device that shares host files with the guest using the P9 protocol.\n\nThis is only supported by Propolis servers compiled with the `falcon` feature.",
         "type": "object",
         "properties": {
           "pci_path": {
@@ -1712,6 +1714,7 @@
         "additionalProperties": false
       },
       "SoftNpuPciPort": {
+        "description": "Describes a SoftNPU PCI device.\n\nThis is only supported by Propolis servers compiled with the `falcon` feature.",
         "type": "object",
         "properties": {
           "pci_path": {
@@ -1729,6 +1732,7 @@
         "additionalProperties": false
       },
       "SoftNpuPort": {
+        "description": "Describes a SoftNPU network port.\n\nThis is only supported by Propolis servers compiled with the `falcon` feature.",
         "type": "object",
         "properties": {
           "backend_name": {