From fcbd2880b8940866024b21ce7bbda8ef72c467af Mon Sep 17 00:00:00 2001 From: Lann Martin Date: Wed, 6 Nov 2024 10:19:08 -0500 Subject: [PATCH] Fix rustdoc lints and formatting Signed-off-by: Lann Martin --- crates/doctor/src/lib.rs | 2 +- crates/doctor/src/wasm.rs | 2 +- .../src/runtime_config/spin.rs | 7 ++-- crates/factor-key-value/src/util.rs | 40 +++++++++++-------- crates/factor-outbound-http/src/intercept.rs | 10 ++--- crates/factors-executor/src/lib.rs | 4 +- crates/factors/src/runtime_config.rs | 2 +- crates/loader/src/cache.rs | 5 ++- crates/locked-app/src/lib.rs | 6 +-- crates/plugins/src/manifest.rs | 2 +- crates/variables/src/azure_key_vault.rs | 34 ++++++++++------ 11 files changed, 66 insertions(+), 48 deletions(-) diff --git a/crates/doctor/src/lib.rs b/crates/doctor/src/lib.rs index 0a5af5c7c2..9a9b60dd22 100644 --- a/crates/doctor/src/lib.rs +++ b/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 diff --git a/crates/doctor/src/wasm.rs b/crates/doctor/src/wasm.rs index b3380db97f..d774cb0844 100644 --- a/crates/doctor/src/wasm.rs +++ b/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. diff --git a/crates/factor-key-value/src/runtime_config/spin.rs b/crates/factor-key-value/src/runtime_config/spin.rs index 0a444b4403..719cd697d4 100644 --- a/crates/factor-key-value/src/runtime_config/spin.rs +++ b/crates/factor-key-value/src/runtime_config/spin.rs @@ -40,10 +40,9 @@ fn store_from_toml_fn(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 diff --git a/crates/factor-key-value/src/util.rs b/crates/factor-key-value/src/util.rs index dcf8cb4e7e..cea72c92b6 100644 --- a/crates/factor-key-value/src/util.rs +++ b/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 and +/// . /// -/// 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 { capacity: NonZeroUsize, inner: T, diff --git a/crates/factor-outbound-http/src/intercept.rs b/crates/factor-outbound-http/src/intercept.rs index 3b583c0764..6afc614720 100644 --- a/crates/factor-outbound-http/src/intercept.rs +++ b/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; } diff --git a/crates/factors-executor/src/lib.rs b/crates/factors-executor/src/lib.rs index 8d2adee770..eac07e20eb 100644 --- a/crates/factors-executor/src/lib.rs +++ b/crates/factors-executor/src/lib.rs @@ -47,7 +47,7 @@ impl FactorsExecutor { 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, 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) -> anyhow::Result<()> { let _ = builder; Ok(()) diff --git a/crates/factors/src/runtime_config.rs b/crates/factors/src/runtime_config.rs index a11fc4583e..ff787c877a 100644 --- a/crates/factors/src/runtime_config.rs +++ b/crates/factors/src/runtime_config.rs @@ -14,7 +14,7 @@ impl FactorRuntimeConfigSource 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<()>; diff --git a/crates/loader/src/cache.rs b/crates/loader/src/cache.rs index b5b5662191..9991de408a 100644 --- a/crates/loader/src/cache.rs +++ b/crates/loader/src/cache.rs @@ -111,11 +111,14 @@ impl Cache { } /// Ensure the expected configuration directories are found in the root. + /// + /// ```text /// └── /// └── registry /// └──manifests /// └──wasm - /// └─-data + /// └──data + /// ``` pub async fn ensure_dirs(&self) -> Result<()> { tracing::debug!("using cache root directory {}", self.root.display()); diff --git a/crates/locked-app/src/lib.rs b/crates/locked-app/src/lib.rs index c33aaa8389..e94cfcf774 100644 --- a/crates/locked-app/src/lib.rs +++ b/crates/locked-app/src/lib.rs @@ -29,13 +29,13 @@ pub type Result = std::result::Result; /// 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. diff --git a/crates/plugins/src/manifest.rs b/crates/plugins/src/manifest.rs index 93b3c0fbf2..fdbb1b00bc 100644 --- a/crates/plugins/src/manifest.rs +++ b/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 +/// #[derive(Serialize, Debug, Deserialize, PartialEq)] #[serde(rename_all = "camelCase")] pub struct PluginManifest { diff --git a/crates/variables/src/azure_key_vault.rs b/crates/variables/src/azure_key_vault.rs index 1ad1df041a..691c980a2b 100644 --- a/crates/variables/src/azure_key_vault.rs +++ b/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: + /// Environmental, }