Fix docs, deny warnings (#1539)

Fixes #1538

Basically, I just ran `RUSTDOCFLAGS="-Dwarnings" cargo doc` until it stopped complaining.

.github/workflows/rust.yml

@@ -77,7 +77,7 @@ jobs:
     - name: Install Pre-Requisites
       run: ./tools/install_builder_prerequisites.sh -y
     - name: Test build documentation
-      run: cargo doc
+      run: RUSTDOCFLAGS="-Dwarnings" cargo doc
 
   build-and-test:
     env:

common/src/api/external/mod.rs

@@ -1459,7 +1459,7 @@ pub struct VpcFirewallRule {
     pub vpc_id: Uuid,
 }
 
-/// Collection of a [`Vpc`]'s firewall rules
+/// Collection of a Vpc's firewall rules
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct VpcFirewallRules {
     pub rules: Vec<VpcFirewallRule>,

gateway-sp-comms/src/communicator.rs

@@ -379,7 +379,7 @@ impl Communicator {
     /// Query all online SPs.
     ///
     /// `ignition_state` should be the state returned by a (recent) call to
-    /// [`get_ignition_state_all()`].
+    /// [`crate::communicator::Communicator::get_ignition_state_all()`].
     ///
     /// All SPs included in `ignition_state` will be yielded by the returned
     /// stream. The order in which they are yielded is undefined; the offline

nexus/db-model/src/device_auth.rs

@@ -3,8 +3,9 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 //! Data structures and token generation routines for the OAuth 2.0
-//! Device Authorization Grant flow. See the module-level documentation
-//! on [`nexus::device_auth`] for an overview of how these are used.
+//! Device Authorization Grant flow. See the module-level documentation in
+//! [device_auth.rs](nexus/src/app/device_auth.rs) for an overview of how these are
+//! used.
 
 use crate::schema::{device_access_token, device_auth_request};
 

nexus/src/app/oximeter.rs

@@ -226,7 +226,7 @@ impl super::Nexus {
     /// be queried.
     /// * `criteria`: Any additional parameters to help narrow down the query
     /// selection further. These parameters are passed directly to
-    /// [oximeter::db::Client::select_timeseries_with].
+    /// [oximeter-db::client::select_timeseries_with].
     /// * `query_params`: Pagination parameter, identifying which page of
     /// results to return.
     /// * `limit`: The maximum number of results to return in a paginated

nexus/src/app/test_interfaces.rs

@@ -11,7 +11,7 @@ use sled_agent_client::Client as SledAgentClient;
 use std::sync::Arc;
 use uuid::Uuid;
 
-/// Exposes additional [`Nexus`] interfaces for use by the test suite
+/// Exposes additional [`super::Nexus`] interfaces for use by the test suite
 #[async_trait]
 pub trait TestInterfaces {
     /// Access the Rack ID of the currently executing Nexus.

nexus/src/db/collection_detach.rs

@@ -32,7 +32,7 @@ use std::fmt::Debug;
 /// Trait to be implemented by structs representing a detachable collection.
 ///
 /// A blanket implementation is provided for traits that implement
-/// [`DatastoreAttachTarget`].
+/// [`crate::db::collection_attach::DatastoreAttachTarget`].
 pub trait DatastoreDetachTarget<ResourceType>:
     DatastoreAttachTargetConfig<ResourceType>
 {

nexus/src/db/collection_detach_many.rs

@@ -32,7 +32,7 @@ use std::fmt::Debug;
 /// Trait to be implemented by structs representing a detachable collection.
 ///
 /// A blanket implementation is provided for traits that implement
-/// [`DatastoreAttachTarget`].
+/// [`crate::db::collection_attach::DatastoreAttachTarget`].
 pub trait DatastoreDetachManyTarget<ResourceType>:
     DatastoreAttachTargetConfig<ResourceType>
 {

nexus/src/db/datastore/saga.rs

@@ -2,7 +2,7 @@
 // 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/.
 
-//! [`DataStore`] methods on [`Saga`]s.
+//! [`DataStore`] methods on [`db::saga_types::Saga`]s.
 
 use super::DataStore;
 use crate::db;

nexus/test-utils-macros/src/lib.rs

@@ -9,10 +9,12 @@ use syn::{parse_macro_input, ItemFn};
 ///
 /// Example usage:
 ///
-/// // #[nexus_test]
-/// // async fn test_my_test_case(cptestctx: &ControlPlaneTestContext) {
-/// //   assert!(true);
-/// // }
+/// ```ignore
+/// #[nexus_test]
+/// async fn test_my_test_case(cptestctx: &ControlPlaneTestContext) {
+///   assert!(true);
+/// }
+/// ```
 ///
 /// We use this instead of implementing Drop on ControlPlaneTestContext because
 /// we want the teardown to only happen when the test doesn't fail (which causes

nexus/test-utils/src/http_testing.rs

@@ -173,7 +173,7 @@ impl<'a> RequestBuilder<'a> {
     /// Record that we expect to get status code `expected_status` in the
     /// response
     ///
-    /// If `expected_status` is not `None`, then [`execute()`] will check this
+    /// If `expected_status` is not `None`, then [`Self::execute()`] will check this
     /// and raise an error if a different status code is found.
     pub fn expect_status(
         mut self,
@@ -185,7 +185,7 @@ impl<'a> RequestBuilder<'a> {
 
     /// Record a list of header names allowed in the response
     ///
-    /// If this function is used, then [`execute()`] will check each header in
+    /// If this function is used, then [`Self::execute()`] will check each header in
     /// the response against this list and raise an error if a header name is
     /// found that's not in this list.
     pub fn expect_allowed_headers<
@@ -234,8 +234,8 @@ impl<'a> RequestBuilder<'a> {
     /// Make the HTTP request using the given `client`, verify the returned
     /// response, and make the response available to the caller
     ///
-    /// This function checks the returned status code (if [`expect_status()`]
-    /// was used), allowed headers (if [`allowed_headers()`] was used), and
+    /// This function checks the returned status code (if [`Self::expect_status()`]
+    /// was used), allowed headers (if [`Self::expect_allowed_headers()`] was used), and
     /// various other properties of the response.
     pub async fn execute(self) -> Result<TestResponse, anyhow::Error> {
         if let Some(error) = self.error {
@@ -468,12 +468,12 @@ pub struct NexusRequest<'a> {
 impl<'a> NexusRequest<'a> {
     /// Create a `NexusRequest` around `request_builder`
     ///
-    /// Most callers should use [`objects_post`], [`object_get`],
-    /// [`object_delete`], or the other wrapper constructors.  If you use this
+    /// Most callers should use [`Self::objects_post`], [`Self::object_get`],
+    /// [`Self::object_delete`], or the other wrapper constructors.  If you use this
     /// function directly, you should set up your `request_builder` first with
     /// whatever HTTP-level stuff you want (including any non-authentication
     /// headers), then call this function to get a `NexusRequest`, then use
-    /// [`authn_as()`] to configure authentication.
+    /// [`Self::authn_as()`] to configure authentication.
     pub fn new(request_builder: RequestBuilder<'a>) -> Self {
         NexusRequest { request_builder }
     }

nexus/types/src/external_api/params.rs

@@ -326,7 +326,7 @@ pub struct ProjectPath {
 
 /// Create-time parameters for an IP Pool.
 ///
-/// See [`IpPool`](omicron_nexus::external_api::views::IpPool)
+/// See [`IpPool`](crate::external_api::views::IpPool)
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct IpPoolCreate {
     #[serde(flatten)]
@@ -762,7 +762,7 @@ pub struct Distribution {
 }
 
 /// Create-time parameters for an
-/// [`GlobalImage`](omicron_common::api::external::GlobalImage)
+/// [`GlobalImage`](crate::external_api::views::GlobalImage)
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct GlobalImageCreate {
     /// common identifying metadata
@@ -780,7 +780,7 @@ pub struct GlobalImageCreate {
 }
 
 /// Create-time parameters for an
-/// [`Image`](omicron_common::api::external::Image)
+/// [`Image`](crate::external_api::views::Image)
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ImageCreate {
     /// common identifying metadata
@@ -796,7 +796,7 @@ pub struct ImageCreate {
 
 // SNAPSHOTS
 
-/// Create-time parameters for a [`Snapshot`](omicron_common::api::external::Snapshot)
+/// Create-time parameters for a [`Snapshot`](crate::external_api::views::Snapshot)
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct SnapshotCreate {
     /// common identifying metadata
@@ -813,7 +813,7 @@ pub struct SnapshotCreate {
 // for creating them internally as we use for types that can be created in the
 // external API.
 
-/// Create-time parameters for a [`UserBuiltin`](crate::db::model::UserBuiltin)
+/// Create-time parameters for a [`UserBuiltin`](crate::external_api::views::UserBuiltin)
 #[derive(Clone, Debug, Deserialize, Serialize, JsonSchema)]
 pub struct UserBuiltinCreate {
     #[serde(flatten)]

nexus/types/src/identity.rs

@@ -19,7 +19,7 @@ use uuid::Uuid;
 /// For durable objects which do not require soft-deletion or descriptions,
 /// consider the [`Asset`] trait instead.
 ///
-/// May be derived from [`macro@db_macros::Resource`].
+/// May be derived from [`macro@db-macros::Resource`].
 pub trait Resource {
     fn id(&self) -> Uuid;
     fn name(&self) -> &Name;
@@ -44,7 +44,7 @@ pub trait Resource {
 /// These are objects similar to [`Resource`], but without
 /// names, descriptions, or soft deletions.
 ///
-/// May be derived from [`macro@db_macros::Asset`].
+/// May be derived from [`macro@db-macros::Asset`].
 pub trait Asset {
     fn id(&self) -> Uuid;
     fn time_created(&self) -> DateTime<Utc>;

openapi/nexus.json

@@ -8156,7 +8156,7 @@
         ]
       },
       "GlobalImageCreate": {
-        "description": "Create-time parameters for an [`GlobalImage`](omicron_common::api::external::GlobalImage)",
+        "description": "Create-time parameters for an [`GlobalImage`](crate::external_api::views::GlobalImage)",
         "type": "object",
         "properties": {
           "block_size": {
@@ -8478,7 +8478,7 @@
         ]
       },
       "ImageCreate": {
-        "description": "Create-time parameters for an [`Image`](omicron_common::api::external::Image)",
+        "description": "Create-time parameters for an [`Image`](crate::external_api::views::Image)",
         "type": "object",
         "properties": {
           "block_size": {
@@ -9010,7 +9010,7 @@
         ]
       },
       "IpPoolCreate": {
-        "description": "Create-time parameters for an IP Pool.\n\nSee [`IpPool`](omicron_nexus::external_api::views::IpPool)",
+        "description": "Create-time parameters for an IP Pool.\n\nSee [`IpPool`](crate::external_api::views::IpPool)",
         "type": "object",
         "properties": {
           "description": {
@@ -10670,7 +10670,7 @@
         ]
       },
       "SnapshotCreate": {
-        "description": "Create-time parameters for a [`Snapshot`](omicron_common::api::external::Snapshot)",
+        "description": "Create-time parameters for a [`Snapshot`](crate::external_api::views::Snapshot)",
         "type": "object",
         "properties": {
           "description": {
@@ -11529,7 +11529,7 @@
         ]
       },
       "VpcFirewallRules": {
-        "description": "Collection of a [`Vpc`]'s firewall rules",
+        "description": "Collection of a Vpc's firewall rules",
         "type": "object",
         "properties": {
           "rules": {

sled-agent/src/bootstrap/ddm_admin_client.rs

@@ -41,7 +41,7 @@ pub struct DdmAdminClient {
 }
 
 impl DdmAdminClient {
-    /// Creates a new [`PeerMonitor`].
+    /// Creates a new [`DdmAdminClient`].
     pub fn new(log: Logger) -> Result<Self, DdmError> {
         let dur = std::time::Duration::from_secs(60);
         let ddmd_addr = SocketAddrV6::new(Ipv6Addr::LOCALHOST, DDMD_PORT, 0, 0);

sled-agent/src/illumos/running_zone.rs

@@ -53,7 +53,7 @@ pub enum EnsureAddressError {
     EnsureAddressError(#[from] crate::illumos::zone::EnsureAddressError),
 }
 
-/// Erros returned from [`RunningZone::get_zone`].
+/// Erros returned from [`RunningZone::get`].
 #[derive(thiserror::Error, Debug)]
 pub enum GetZoneError {
     #[error("While looking up zones with prefix '{prefix}', could not get zones: {err}")]

sled-agent/src/illumos/vnic.rs

@@ -36,11 +36,11 @@ impl<DL: VnicSource + Clone> VnicAllocator<DL> {
     /// ranges of Vnic names, for example:
     ///
     /// VnicAllocator::new("Instance")
-    /// - oxGuestInstance[NNN]
-    /// - oxControlInstance[NNN]
+    /// - oxGuestInstance0
+    /// - oxControlInstance0
     ///
     /// VnicAllocator::new("Storage") produces
-    /// - oxControlStorage[NNN]
+    /// - oxControlStorage0
     pub fn new<S: AsRef<str>>(scope: S, data_link: DL) -> Self {
         Self {
             value: Arc::new(AtomicU64::new(0)),

sled-agent/src/illumos/zfs.rs

@@ -66,7 +66,7 @@ enum GetValueErrorRaw {
     MissingValue,
 }
 
-/// Error returned by [`Zfs:get_oxide_value`].
+/// Error returned by [`Zfs::get_oxide_value`].
 #[derive(thiserror::Error, Debug)]
 #[error("Failed to get value '{name}' from filesystem {filesystem}: {err}")]
 pub struct GetValueError {