From 92d65307c123ef078c42f5a86f054dfcffc267a6 Mon Sep 17 00:00:00 2001 From: iliana etaoin Date: Fri, 21 Jun 2024 08:50:19 -0700 Subject: [PATCH] fix `cargo doc` checks in CI (#5924) Fixes #5739. Also adds `--no-deps` because this is intended as a check to ensure the docs, if someone wants to generate them, are valid and build without warnings. Warnings in dependencies' docs are ignored anyway. --- .cargo/config.toml | 6 ++++++ .github/buildomat/build-and-test.sh | 2 +- .github/buildomat/jobs/clippy.sh | 2 +- .github/workflows/rust.yml | 2 +- nexus/auth/src/authz/api_resources.rs | 10 +++++----- nexus/db-queries/src/db/datastore/sled.rs | 4 ++-- nexus/db-queries/src/db/datastore/update.rs | 2 +- .../planning/src/blueprint_builder/builder.rs | 13 +++++++------ nexus/src/app/instance_network.rs | 3 ++- nexus/src/app/sagas/volume_delete.rs | 6 +++++- nexus/types/src/deployment/blueprint_diff.rs | 2 +- nexus/types/src/deployment/blueprint_display.rs | 3 +-- oximeter/db/src/oxql/ast/grammar.rs | 4 ++-- sled-agent/src/sim/instance.rs | 10 +++++----- wicket/src/ui/panes/update.rs | 2 +- 15 files changed, 41 insertions(+), 30 deletions(-) diff --git a/.cargo/config.toml b/.cargo/config.toml index f658f146c9..c5b6fcd9d4 100644 --- a/.cargo/config.toml +++ b/.cargo/config.toml @@ -4,6 +4,12 @@ # binaries and the test suite. There's no need for typical library # documentation of public interfaces.) # +# NOTE: If you change this, also change the `RUSTDOCFLAGS` values in the various +# CI scripts: +# - .github/buildomat/build-and-test.sh +# - .github/buildomat/jobs/clippy.sh +# - .github/workflows/rust.yml +# [build] rustdocflags = "--document-private-items" diff --git a/.github/buildomat/build-and-test.sh b/.github/buildomat/build-and-test.sh index cc344522db..1e4b655cb9 100755 --- a/.github/buildomat/build-and-test.sh +++ b/.github/buildomat/build-and-test.sh @@ -54,7 +54,7 @@ ptime -m bash ./tools/install_builder_prerequisites.sh -y # banner build export RUSTFLAGS="-D warnings" -export RUSTDOCFLAGS="-D warnings" +export RUSTDOCFLAGS="--document-private-items -D warnings" # When running on illumos we need to pass an additional runpath that is # usually configured via ".cargo/config" but the `RUSTFLAGS` env variable # takes precedence. This path contains oxide specific libraries such as diff --git a/.github/buildomat/jobs/clippy.sh b/.github/buildomat/jobs/clippy.sh index 7da32ec331..71aa04c907 100755 --- a/.github/buildomat/jobs/clippy.sh +++ b/.github/buildomat/jobs/clippy.sh @@ -30,4 +30,4 @@ ptime -m bash ./tools/install_builder_prerequisites.sh -y banner clippy export CARGO_INCREMENTAL=0 ptime -m cargo xtask clippy -RUSTDOCFLAGS="-Dwarnings" ptime -m cargo doc --workspace +RUSTDOCFLAGS="--document-private-items -D warnings" ptime -m cargo doc --workspace --no-deps diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 1888481ba2..2ef2783108 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -108,4 +108,4 @@ jobs: - name: Install Pre-Requisites run: ./tools/install_builder_prerequisites.sh -y - name: Test build documentation - run: RUSTDOCFLAGS="-Dwarnings" cargo doc --workspace + run: RUSTDOCFLAGS="--document-private-items -D warnings" cargo doc --workspace --no-deps diff --git a/nexus/auth/src/authz/api_resources.rs b/nexus/auth/src/authz/api_resources.rs index 98a24b68b5..f4c91dc544 100644 --- a/nexus/auth/src/authz/api_resources.rs +++ b/nexus/auth/src/authz/api_resources.rs @@ -5,11 +5,11 @@ //! Authz types for resources in the API hierarchy //! //! The general pattern in Nexus for working with an object is to look it up -//! (see [`crate::db::lookup::LookupPath`]) and get back a so-called `authz` -//! type. This type uniquely identifies the resource regardless of any other -//! changes (e.g., name change or moving it to a different parent collection). -//! The various datastore functions that modify API resources accept these -//! `authz` types. +//! (see `nexus_db_queries::db::lookup::LookupPath`) and get back a so-called +//! `authz` type. This type uniquely identifies the resource regardless of +//! any other changes (e.g., name change or moving it to a different parent +//! collection). The various datastore functions that modify API resources +//! accept these `authz` types. //! //! The `authz` types can be passed to //! [`crate::context::OpContext::authorize()`] to do an authorization check -- diff --git a/nexus/db-queries/src/db/datastore/sled.rs b/nexus/db-queries/src/db/datastore/sled.rs index bf43b9182d..381b25dc17 100644 --- a/nexus/db-queries/src/db/datastore/sled.rs +++ b/nexus/db-queries/src/db/datastore/sled.rs @@ -695,7 +695,7 @@ impl SledTransition { /// (which is always considered valid). /// /// For a more descriptive listing of valid transitions, see - /// [`test_sled_transitions`]. + /// `test_sled_transitions`. fn valid_old_policies(&self) -> Vec { use SledPolicy::*; use SledProvisionPolicy::*; @@ -731,7 +731,7 @@ impl SledTransition { /// (which is always considered valid). /// /// For a more descriptive listing of valid transitions, see - /// [`test_sled_transitions`]. + /// `test_sled_transitions`. fn valid_old_states(&self) -> Vec { use SledState::*; diff --git a/nexus/db-queries/src/db/datastore/update.rs b/nexus/db-queries/src/db/datastore/update.rs index d73a3d903f..37339beb62 100644 --- a/nexus/db-queries/src/db/datastore/update.rs +++ b/nexus/db-queries/src/db/datastore/update.rs @@ -25,7 +25,7 @@ use omicron_uuid_kinds::TufRepoKind; use omicron_uuid_kinds::TypedUuid; use swrite::{swrite, SWrite}; -/// The return value of [`DataStore::update_tuf_repo_description_insert`]. +/// The return value of [`DataStore::update_tuf_repo_insert`]. /// /// This is similar to [`external::TufRepoInsertResponse`], but uses /// nexus-db-model's types instead of external types. diff --git a/nexus/reconfigurator/planning/src/blueprint_builder/builder.rs b/nexus/reconfigurator/planning/src/blueprint_builder/builder.rs index 9d7c542eda..c93781a073 100644 --- a/nexus/reconfigurator/planning/src/blueprint_builder/builder.rs +++ b/nexus/reconfigurator/planning/src/blueprint_builder/builder.rs @@ -1164,12 +1164,13 @@ impl<'a> BlueprintZonesBuilder<'a> { /// Helper for working with sets of disks on each sled /// -/// Tracking the set of disks is slightly non-trivial because we need to bump -/// the per-sled generation number iff the disks are changed. So we need to -/// keep track of whether we've changed the disks relative to the parent -/// blueprint. We do this by keeping a copy of any [`BlueprintDisksConfig`] -/// that we've changed and a _reference_ to the parent blueprint's disks. This -/// struct makes it easy for callers iterate over the right set of disks. +/// Tracking the set of disks is slightly non-trivial because we need to +/// bump the per-sled generation number iff the disks are changed. So +/// we need to keep track of whether we've changed the disks relative +/// to the parent blueprint. We do this by keeping a copy of any +/// [`BlueprintPhysicalDisksConfig`] that we've changed and a _reference_ to +/// the parent blueprint's disks. This struct makes it easy for callers iterate +/// over the right set of disks. struct BlueprintDisksBuilder<'a> { changed_disks: BTreeMap, parent_disks: &'a BTreeMap, diff --git a/nexus/src/app/instance_network.rs b/nexus/src/app/instance_network.rs index b1ad2bb6fc..c2d46c5499 100644 --- a/nexus/src/app/instance_network.rs +++ b/nexus/src/app/instance_network.rs @@ -29,8 +29,9 @@ use std::str::FromStr; use uuid::Uuid; use super::background::BackgroundTasks; +use super::Nexus; -impl super::Nexus { +impl Nexus { /// Returns the set of switches with uplinks configured and boundary /// services enabled. pub(crate) async fn boundary_switches( diff --git a/nexus/src/app/sagas/volume_delete.rs b/nexus/src/app/sagas/volume_delete.rs index bfd8e6616c..b9e02538b2 100644 --- a/nexus/src/app/sagas/volume_delete.rs +++ b/nexus/src/app/sagas/volume_delete.rs @@ -332,8 +332,9 @@ async fn svd_delete_crucible_snapshot_records( /// It's insufficient to rely on the struct of CrucibleResources to clean up /// that is returned as part of svd_decrease_crucible_resource_count. Imagine a /// disk that is composed of three regions (a subset of -/// [`VolumeConstructionRequest`] is shown here): +/// [`sled_agent_client::types::VolumeConstructionRequest`] is shown here): /// +/// ```json /// { /// "type": "volume", /// "id": "6b353c87-afac-4ee2-b71a-6fe35fcf9e46", @@ -352,9 +353,11 @@ async fn svd_delete_crucible_snapshot_records( /// ], /// "read_only_parent": null, /// } +/// ``` /// /// Taking a snapshot of this will produce the following volume: /// +/// ```json /// { /// "type": "volume", /// "id": "1ef7282e-a3fb-4222-85a8-b16d3fbfd738", <-- new UUID @@ -373,6 +376,7 @@ async fn svd_delete_crucible_snapshot_records( /// ], /// "read_only_parent": null, /// } +/// ``` /// /// The snapshot targets will use the same IP but different port: snapshots are /// initially located on the same filesystem as their region. diff --git a/nexus/types/src/deployment/blueprint_diff.rs b/nexus/types/src/deployment/blueprint_diff.rs index 17631e692d..4f2ee9ed3b 100644 --- a/nexus/types/src/deployment/blueprint_diff.rs +++ b/nexus/types/src/deployment/blueprint_diff.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/. -//! Types helpful for diffing [`Blueprints`]. +//! Types helpful for diffing blueprints. use super::blueprint_display::{ constants::*, linear_table_modified, linear_table_unchanged, BpDiffState, diff --git a/nexus/types/src/deployment/blueprint_display.rs b/nexus/types/src/deployment/blueprint_display.rs index 5d106b6ef3..2b0e4cab6c 100644 --- a/nexus/types/src/deployment/blueprint_display.rs +++ b/nexus/types/src/deployment/blueprint_display.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/. -//! Types helpful for rendering [`Blueprints`]. +//! Types helpful for rendering blueprints. use omicron_common::api::external::Generation; use std::fmt; @@ -176,7 +176,6 @@ pub trait BpSledSubtableData { } /// A table specific to a sled resource, such as a zone or disk. -/// `BpSledSubtable`s are always nested under [`BpSledTable`]s. pub struct BpSledSubtable { table_name: &'static str, column_names: &'static [&'static str], diff --git a/oximeter/db/src/oxql/ast/grammar.rs b/oximeter/db/src/oxql/ast/grammar.rs index a644dff41d..a7585402b6 100644 --- a/oximeter/db/src/oxql/ast/grammar.rs +++ b/oximeter/db/src/oxql/ast/grammar.rs @@ -257,7 +257,7 @@ peg::parser! { /// /// We support the following common escape sequences: /// - /// ```ignore + /// ```text /// \n /// \r /// \t @@ -271,7 +271,7 @@ peg::parser! { /// styles if required, by writing them as their Unicode escape /// sequences. For example, this string: /// - /// ```ignore + /// ```text /// "this string has \u{22} in it" /// ``` /// diff --git a/sled-agent/src/sim/instance.rs b/sled-agent/src/sim/instance.rs index 06739df8fa..be6c63f53a 100644 --- a/sled-agent/src/sim/instance.rs +++ b/sled-agent/src/sim/instance.rs @@ -43,11 +43,11 @@ enum MonitorChange { /// integration tests. /// /// The simulated instance contains a fake instance state stored as a -/// [`propolis_client::api::InstanceStateMonitorResponse`]. Transition requests -/// enqueue changes to either the instance state or the migration status fields -/// of this response. When poked, the simulated instance applies the next -/// transition, translates this to an observed Propolis state, and sends it -/// off for processing. +/// [`propolis_client::types::InstanceStateMonitorResponse`]. Transition +/// requests enqueue changes to either the instance state or the migration +/// status fields of this response. When poked, the simulated instance applies +/// the next transition, translates this to an observed Propolis state, and +/// sends it off for processing. #[derive(Debug)] struct SimInstanceInner { /// The current simulated instance state. diff --git a/wicket/src/ui/panes/update.rs b/wicket/src/ui/panes/update.rs index 712ba778b5..6269228bc2 100644 --- a/wicket/src/ui/panes/update.rs +++ b/wicket/src/ui/panes/update.rs @@ -150,7 +150,7 @@ pub struct UpdatePane { /// TODO: Move following state into global `State` so that recorder snapshots /// capture all state. /// - /// TODO: The generic parameter is carried over from earlier versions + /// TODO: The usize generic parameter is carried over from earlier versions /// of tui-tree-widget, but there's likely a better index type. tree_state: TreeState, items: Vec>,