From 45d513d3a23c0c5bffd6cfe436d3302fede0be52 Mon Sep 17 00:00:00 2001 From: Sean Klein Date: Wed, 3 Aug 2022 14:20:36 -0400 Subject: [PATCH 1/3] Fix docs, deny warnings --- .github/workflows/rust.yml | 2 +- common/src/api/external/mod.rs | 2 +- gateway-sp-comms/src/communicator.rs | 2 +- nexus/db-model/src/device_auth.rs | 5 +++-- nexus/src/app/oximeter.rs | 2 +- nexus/src/app/test_interfaces.rs | 2 +- nexus/src/db/collection_detach.rs | 2 +- nexus/src/db/collection_detach_many.rs | 2 +- nexus/src/db/datastore/saga.rs | 2 +- nexus/test-utils-macros/src/lib.rs | 10 ++++++---- nexus/test-utils/src/http_testing.rs | 14 +++++++------- nexus/types/src/external_api/params.rs | 10 +++++----- nexus/types/src/identity.rs | 4 ++-- sled-agent/src/bootstrap/ddm_admin_client.rs | 2 +- sled-agent/src/illumos/running_zone.rs | 2 +- sled-agent/src/illumos/vnic.rs | 6 +++--- sled-agent/src/illumos/zfs.rs | 2 +- 17 files changed, 37 insertions(+), 34 deletions(-) diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 3dff35be91..9d63cd8976 100644 --- a/.github/workflows/rust.yml +++ b/.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: diff --git a/common/src/api/external/mod.rs b/common/src/api/external/mod.rs index e348544299..e3cc4bc2ba 100644 --- a/common/src/api/external/mod.rs +++ b/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, diff --git a/gateway-sp-comms/src/communicator.rs b/gateway-sp-comms/src/communicator.rs index c86fd277a7..1101deffa1 100644 --- a/gateway-sp-comms/src/communicator.rs +++ b/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 diff --git a/nexus/db-model/src/device_auth.rs b/nexus/db-model/src/device_auth.rs index 67285b809a..aa68749de0 100644 --- a/nexus/db-model/src/device_auth.rs +++ b/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}; diff --git a/nexus/src/app/oximeter.rs b/nexus/src/app/oximeter.rs index 050e228b71..e59a67c450 100644 --- a/nexus/src/app/oximeter.rs +++ b/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 diff --git a/nexus/src/app/test_interfaces.rs b/nexus/src/app/test_interfaces.rs index ccc4353437..a7e56b218a 100644 --- a/nexus/src/app/test_interfaces.rs +++ b/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. diff --git a/nexus/src/db/collection_detach.rs b/nexus/src/db/collection_detach.rs index 531a51500c..3ae384d74e 100644 --- a/nexus/src/db/collection_detach.rs +++ b/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: DatastoreAttachTargetConfig { diff --git a/nexus/src/db/collection_detach_many.rs b/nexus/src/db/collection_detach_many.rs index 135d3b83b6..4288fc7b04 100644 --- a/nexus/src/db/collection_detach_many.rs +++ b/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: DatastoreAttachTargetConfig { diff --git a/nexus/src/db/datastore/saga.rs b/nexus/src/db/datastore/saga.rs index 8427735bd4..86520897f8 100644 --- a/nexus/src/db/datastore/saga.rs +++ b/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; diff --git a/nexus/test-utils-macros/src/lib.rs b/nexus/test-utils-macros/src/lib.rs index 865c2c8492..b1eab80cd7 100644 --- a/nexus/test-utils-macros/src/lib.rs +++ b/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); -/// // } +/// ```no_run +/// #[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 diff --git a/nexus/test-utils/src/http_testing.rs b/nexus/test-utils/src/http_testing.rs index ac00ddbc29..cd80ce0e1d 100644 --- a/nexus/test-utils/src/http_testing.rs +++ b/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 { 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 } } diff --git a/nexus/types/src/external_api/params.rs b/nexus/types/src/external_api/params.rs index 0f59257a61..b1ed4ec334 100644 --- a/nexus/types/src/external_api/params.rs +++ b/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)] diff --git a/nexus/types/src/identity.rs b/nexus/types/src/identity.rs index 2092afe888..d8baf5782e 100644 --- a/nexus/types/src/identity.rs +++ b/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; diff --git a/sled-agent/src/bootstrap/ddm_admin_client.rs b/sled-agent/src/bootstrap/ddm_admin_client.rs index cbf150c22b..7498610568 100644 --- a/sled-agent/src/bootstrap/ddm_admin_client.rs +++ b/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 { let dur = std::time::Duration::from_secs(60); let ddmd_addr = SocketAddrV6::new(Ipv6Addr::LOCALHOST, DDMD_PORT, 0, 0); diff --git a/sled-agent/src/illumos/running_zone.rs b/sled-agent/src/illumos/running_zone.rs index 5a07c17c15..f58628341e 100644 --- a/sled-agent/src/illumos/running_zone.rs +++ b/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}")] diff --git a/sled-agent/src/illumos/vnic.rs b/sled-agent/src/illumos/vnic.rs index c9355446ef..3fbc5b77b2 100644 --- a/sled-agent/src/illumos/vnic.rs +++ b/sled-agent/src/illumos/vnic.rs @@ -36,11 +36,11 @@ impl VnicAllocator
{ /// 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>(scope: S, data_link: DL) -> Self { Self { value: Arc::new(AtomicU64::new(0)), diff --git a/sled-agent/src/illumos/zfs.rs b/sled-agent/src/illumos/zfs.rs index e47825d058..7ffe7c6143 100644 --- a/sled-agent/src/illumos/zfs.rs +++ b/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 { From b4f99f1f65bcf105ff05ef96b8eefe2ffa67acd7 Mon Sep 17 00:00:00 2001 From: Sean Klein Date: Wed, 3 Aug 2022 17:18:57 -0400 Subject: [PATCH 2/3] openapi --- openapi/nexus.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/openapi/nexus.json b/openapi/nexus.json index bd1ca1e29f..80c9bf04f8 100644 --- a/openapi/nexus.json +++ b/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": { From b720e57c1377c04fb82c05fda9bf9f51026c50b1 Mon Sep 17 00:00:00 2001 From: Sean Klein Date: Wed, 3 Aug 2022 18:27:36 -0400 Subject: [PATCH 3/3] Ignore doc in macro docs --- nexus/test-utils-macros/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/nexus/test-utils-macros/src/lib.rs b/nexus/test-utils-macros/src/lib.rs index b1eab80cd7..451e65867a 100644 --- a/nexus/test-utils-macros/src/lib.rs +++ b/nexus/test-utils-macros/src/lib.rs @@ -9,7 +9,7 @@ use syn::{parse_macro_input, ItemFn}; /// /// Example usage: /// -/// ```no_run +/// ```ignore /// #[nexus_test] /// async fn test_my_test_case(cptestctx: &ControlPlaneTestContext) { /// assert!(true);