Merge pull request #2914 from lann/doc-lints

Fix rustdoc lints and formatting

crates/doctor/src/lib.rs

@@ -128,7 +128,7 @@ pub trait Diagnostic: Send + Sync {
     /// A [`Diagnosis`] representing the problem(s) this can detect.
     type Diagnosis: Diagnosis;
 
-    /// Check the given [`Patient`], returning any problem(s) found.
+    /// Check the given [`PatientApp`], returning any problem(s) found.
     ///
     /// If multiple _independently addressable_ problems are found, this may
     /// return multiple instances. If two "logically separate" problems would

crates/doctor/src/wasm.rs

@@ -58,7 +58,7 @@ impl PatientWasm {
     }
 }
 
-/// WasmDiagnose helps implement [`Diagnose`] for Wasm source problems.
+/// WasmDiagnostic helps implement [`Diagnostic`] for Wasm source problems.
 #[async_trait]
 pub trait WasmDiagnostic {
     /// A [`Diagnosis`] representing the problem(s) this can detect.

crates/factor-key-value/src/runtime_config/spin.rs

@@ -40,10 +40,9 @@ fn store_from_toml_fn<T: MakeKeyValueStore>(provider_type: T) -> StoreFromToml {
 
 /// Converts from toml based runtime configuration into a [`RuntimeConfig`].
 ///
-/// Also acts as [`DefaultLabelResolver`].
-///
-/// The various store types (i.e., the "type" field in the toml field) are registered with the
-/// resolver using `add_store_type`. The default store for a label is registered using `add_default_store`.
+/// The various store types (i.e., the "type" field in the toml field) are
+/// registered with the resolver using `add_store_type`. The default store for a
+/// label is registered using `add_default_store`.
 #[derive(Default, Clone)]
 pub struct RuntimeConfigResolver {
     /// A map of store types to a function that returns the appropriate store

crates/factor-key-value/src/util.rs

@@ -46,30 +46,38 @@ impl StoreManager for DelegatingStoreManager {
     }
 }
 
-/// Wrap each `Store` produced by the inner `StoreManager` in an asynchronous, write-behind cache.
+/// Wrap each `Store` produced by the inner `StoreManager` in an asynchronous,
+/// write-behind cache.
 ///
 /// This serves two purposes:
 ///
 /// - Improve performance with slow and/or distant stores
 ///
-/// - Provide a relaxed consistency guarantee vs. what a fully synchronous store provides
+/// - Provide a relaxed consistency guarantee vs. what a fully synchronous store
+///   provides
 ///
-/// The latter is intended to prevent guests from coming to rely on the synchronous consistency model of an
-/// existing implementation which may later be replaced with one providing a more relaxed, asynchronous
-/// (i.e. "eventual") consistency model.  See also https://www.hyrumslaw.com/ and https://xkcd.com/1172/.
+/// The latter is intended to prevent guests from coming to rely on the
+/// synchronous consistency model of an existing implementation which may later
+/// be replaced with one providing a more relaxed, asynchronous (i.e.
+/// "eventual") consistency model.  See also <https://www.hyrumslaw.com/> and
+/// <https://xkcd.com/1172/>.
 ///
-/// This implementation provides a "read-your-writes", asynchronous consistency model such that values are
-/// immediately available for reading as soon as they are written as long as the read(s) hit the same cache as the
-/// write(s).  Reads and writes through separate caches (e.g. separate guest instances or separately-opened
-/// references to the same store within a single instance) are _not_ guaranteed to be consistent; not only is
-/// cross-cache consistency subject to scheduling and/or networking delays, a given tuple is never refreshed from
-/// the backing store once added to a cache since this implementation is intended for use only by short-lived guest
-/// instances.
+/// This implementation provides a "read-your-writes", asynchronous consistency
+/// model such that values are immediately available for reading as soon as they
+/// are written as long as the read(s) hit the same cache as the write(s).
+/// Reads and writes through separate caches (e.g. separate guest instances or
+/// separately-opened references to the same store within a single instance) are
+/// _not_ guaranteed to be consistent; not only is cross-cache consistency
+/// subject to scheduling and/or networking delays, a given tuple is never
+/// refreshed from the backing store once added to a cache since this
+/// implementation is intended for use only by short-lived guest instances.
 ///
-/// Note that, because writes are asynchronous and return immediately, durability is _not_ guaranteed.  I/O errors
-/// may occur asynchronously after the write operation has returned control to the guest, which may result in the
-/// write being lost without the guest knowing.  In the future, a separate `write-durable` function could be added
-/// to key-value.wit to provide either synchronous or asynchronous feedback on durability for guests which need it.
+/// Note that, because writes are asynchronous and return immediately,
+/// durability is _not_ guaranteed.  I/O errors may occur asynchronously after
+/// the write operation has returned control to the guest, which may result in
+/// the write being lost without the guest knowing.  In the future, a separate
+/// `write-durable` function could be added to key-value.wit to provide either
+/// synchronous or asynchronous feedback on durability for guests which need it.
 pub struct CachingStoreManager<T> {
     capacity: NonZeroUsize,
     inner: T,

crates/factor-outbound-http/src/intercept.rs

@@ -6,18 +6,18 @@ use wasmtime_wasi_http::{body::HyperOutgoingBody, HttpResult};
 pub type HyperBody = HyperOutgoingBody;
 
 /// An outbound HTTP request interceptor to be used with
-/// [`InstanceState::set_request_interceptor`].
+/// [`super::InstanceState::set_request_interceptor`].
 #[async_trait]
 pub trait OutboundHttpInterceptor: Send + Sync {
     /// Intercept an outgoing HTTP request.
     ///
-    /// If this method returns [`InterceptedResponse::Continue`], the (possibly
+    /// If this method returns [`InterceptOutcome::Continue`], the (possibly
     /// updated) request will be passed on to the default outgoing request
     /// handler.
     ///
-    /// If this method returns [`InterceptedResponse::Intercepted`], the inner
-    /// result will be returned as the result of the request, bypassing the
-    /// default handler. The `request` will also be dropped immediately.
+    /// If this method returns [`InterceptOutcome::Complete`], the inner result
+    /// will be returned as the result of the request, bypassing the default
+    /// handler. The `request` will also be dropped immediately.
     async fn intercept(&self, request: InterceptRequest) -> HttpResult<InterceptOutcome>;
 }
 

crates/factors-executor/src/lib.rs

@@ -47,7 +47,7 @@ impl<T: RuntimeFactors, U: Send + 'static> FactorsExecutor<T, U> {
         self.hooks.push(Box::new(hooks));
     }
 
-    /// Loads a [`FactorsApp`] with this executor.
+    /// Loads a [`App`] with this executor.
     pub async fn load_app(
         self: Arc<Self>,
         app: App,
@@ -93,7 +93,7 @@ where
         Ok(())
     }
 
-    /// Prepare instance hooks run immediately before [`FactorsExecutor::prepare`] returns.
+    /// Prepare instance hooks run immediately before [`FactorsExecutorApp::prepare`] returns.
     fn prepare_instance(&self, builder: &mut FactorsInstanceBuilder<T, U>) -> anyhow::Result<()> {
         let _ = builder;
         Ok(())

crates/factors/src/runtime_config.rs

@@ -14,7 +14,7 @@ impl<F: Factor> FactorRuntimeConfigSource<F> for () {
     }
 }
 
-/// Run some finalization logic on a [`RuntimeConfigSource`].
+/// Run some finalization logic on a [`FactorRuntimeConfigSource`].
 pub trait RuntimeConfigSourceFinalizer {
     /// Finalize the runtime config source.
     fn finalize(&mut self) -> anyhow::Result<()>;

crates/loader/src/cache.rs

@@ -111,11 +111,14 @@ impl Cache {
     }
 
     /// Ensure the expected configuration directories are found in the root.
+    ///
+    /// ```text
     /// └── <configuration-root>
     ///     └── registry
     ///             └──manifests
     ///             └──wasm
-    ///             └─-data
+    ///             └──data
+    /// ```
     pub async fn ensure_dirs(&self) -> Result<()> {
         tracing::debug!("using cache root directory {}", self.root.display());
 

crates/locked-app/src/lib.rs

@@ -29,13 +29,13 @@ pub type Result<T> = std::result::Result<T, Error>;
 /// Errors returned by methods in this crate.
 #[derive(Debug, thiserror::Error)]
 pub enum Error {
-    /// An error propagated from the [`spin_core`] crate.
+    /// An error propagated from the `spin_core` crate.
     #[error(transparent)]
     CoreError(anyhow::Error),
-    /// An error from a [`DynamicHostComponent`].
+    /// An error from a `DynamicHostComponent`.
     #[error("host component error: {0:#}")]
     HostComponentError(#[source] anyhow::Error),
-    /// An error from a [`Loader`] implementation.
+    /// An error from a `Loader` implementation.
     #[error(transparent)]
     LoaderError(anyhow::Error),
     /// An error indicating missing or unexpected metadata.

crates/plugins/src/manifest.rs

@@ -9,7 +9,7 @@ use crate::PluginStore;
 
 /// Expected schema of a plugin manifest. Should match the latest Spin plugin
 /// manifest JSON schema:
-/// https://github.com/fermyon/spin-plugins/tree/main/json-schema
+/// <https://github.com/fermyon/spin-plugins/tree/main/json-schema>
 #[derive(Serialize, Debug, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
 pub struct PluginManifest {

crates/variables/src/azure_key_vault.rs

@@ -11,8 +11,8 @@ use tracing::{instrument, Level};
 
 /// Azure KeyVault runtime config literal options for authentication
 ///
-/// Some of these fields are optional. Whether they are set determines whether environmental variables
-/// will be used to resolve the information instead.
+/// Some of these fields are optional. Whether they are set determines whether
+/// environmental variables will be used to resolve the information instead.
 #[derive(Clone, Debug, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct AzureKeyVaultVariablesConfig {
@@ -61,10 +61,10 @@ pub enum AzureKeyVaultAuthOptions {
         tenant_id: String,
         authority_host: AzureAuthorityHost,
     },
-    /// Environmental indicates that the environment variables of the process should be used to
-    /// create the TokenCredential for the Cosmos client. This will use the Azure Rust SDK's
-    /// DefaultCredentialChain to derive the TokenCredential based on what environment variables
-    /// have been set.
+    /// Environmental indicates that the environment variables of the process
+    /// should be used to create the TokenCredential for the Cosmos client. This
+    /// will use the Azure Rust SDK's DefaultCredentialChain to derive the
+    /// TokenCredential based on what environment variables have been set.
     ///
     /// Service Principal with client secret:
     /// - `AZURE_TENANT_ID`: ID of the service principal's Azure tenant.
@@ -74,24 +74,32 @@ pub enum AzureKeyVaultAuthOptions {
     /// Service Principal with certificate:
     /// - `AZURE_TENANT_ID`: ID of the service principal's Azure tenant.
     /// - `AZURE_CLIENT_ID`: the service principal's client ID.
-    /// - `AZURE_CLIENT_CERTIFICATE_PATH`: path to a PEM or PKCS12 certificate file including the private key.
-    /// - `AZURE_CLIENT_CERTIFICATE_PASSWORD`: (optional) password for the certificate file.
+    /// - `AZURE_CLIENT_CERTIFICATE_PATH`: path to a PEM or PKCS12 certificate
+    ///   file including the private key.
+    /// - `AZURE_CLIENT_CERTIFICATE_PASSWORD`: (optional) password for the
+    ///   certificate file.
     ///
-    /// Workload Identity (Kubernetes, injected by the Workload Identity mutating webhook):
+    /// Workload Identity (Kubernetes, injected by the Workload Identity
+    /// mutating webhook):
     /// - `AZURE_TENANT_ID`: ID of the service principal's Azure tenant.
     /// - `AZURE_CLIENT_ID`: the service principal's client ID.
-    /// - `AZURE_FEDERATED_TOKEN_FILE`: TokenFilePath is the path of a file containing a Kubernetes service account token.
+    /// - `AZURE_FEDERATED_TOKEN_FILE`: TokenFilePath is the path of a file
+    ///   containing a Kubernetes service account token.
     ///
     /// Managed Identity (User Assigned or System Assigned identities):
-    /// - `AZURE_CLIENT_ID`: (optional) if using a user assigned identity, this will be the client ID of the identity.
+    /// - `AZURE_CLIENT_ID`: (optional) if using a user assigned identity, this
+    ///   will be the client ID of the identity.
     ///
     /// Azure CLI:
     /// - `AZURE_TENANT_ID`: (optional) use a specific tenant via the Azure CLI.
     ///
     /// Common across each:
-    /// - `AZURE_AUTHORITY_HOST`: (optional) the host for the identity provider. For example, for Azure public cloud the host defaults to "https://login.microsoftonline.com".
+    /// - `AZURE_AUTHORITY_HOST`: (optional) the host for the identity provider.
+    ///   For example, for Azure public cloud the host defaults to
+    ///   `"https://login.microsoftonline.com"`.
     ///
-    /// See also: https://github.com/Azure/azure-sdk-for-rust/blob/main/sdk/identity/README.md
+    /// See also:
+    /// <https://github.com/Azure/azure-sdk-for-rust/blob/main/sdk/identity/README.md>
     Environmental,
 }