From 080b501ba8a5615a862b704c9a0955655d64989c Mon Sep 17 00:00:00 2001 From: Piepmatz Date: Wed, 29 Jan 2025 01:09:53 +0100 Subject: [PATCH] Fix `cargo doc` Warnings (#14948) # Description As an avid `cargo doc` enjoyer I realized we had some doc warnings, so I fixed them. After this PR `cargo doc --workspace` should stop throwing warnings. # User-Facing Changes No code changes. # Tests + Formatting - :green_circle: `toolkit fmt` - :green_circle: `toolkit clippy` - :green_circle: `toolkit test` - :green_circle: `toolkit test stdlib` # After Submitting We could add a `cargo doc` CI pipeline but usually running a full `cargo doc` takes like forever, so maybe we don't want that. --- crates/nu-plugin-core/src/serializers/mod.rs | 4 ++-- crates/nu-protocol/src/engine/engine_state.rs | 8 ++++---- crates/nu-protocol/src/engine/state_working_set.rs | 11 ++++++----- crates/nu-protocol/src/errors/shell_error/io.rs | 7 ++++--- crates/nu-protocol/src/pipeline/pipeline_data.rs | 2 +- crates/nu-protocol/src/span.rs | 5 +++-- crates/nu-protocol/src/ty.rs | 5 +++-- crates/nu-protocol/src/value/mod.rs | 2 +- 8 files changed, 24 insertions(+), 20 deletions(-) diff --git a/crates/nu-plugin-core/src/serializers/mod.rs b/crates/nu-plugin-core/src/serializers/mod.rs index 8fe09cc4f6..545aecbf7d 100644 --- a/crates/nu-plugin-core/src/serializers/mod.rs +++ b/crates/nu-plugin-core/src/serializers/mod.rs @@ -12,7 +12,7 @@ mod tests; pub trait Encoder: Clone + Send + Sync { /// Serialize a value in the [`PluginEncoder`]s format /// - /// Returns [`ShellError::IOError`] if there was a problem writing, or + /// Returns [`ShellError::Io`] if there was a problem writing, or /// [`ShellError::PluginFailedToEncode`] for a serialization error. fn encode(&self, data: &T, writer: &mut impl std::io::Write) -> Result<(), ShellError>; @@ -20,7 +20,7 @@ pub trait Encoder: Clone + Send + Sync { /// /// Returns `None` if there is no more output to receive. /// - /// Returns [`ShellError::IOError`] if there was a problem reading, or + /// Returns [`ShellError::Io`] if there was a problem reading, or /// [`ShellError::PluginFailedToDecode`] for a deserialization error. fn decode(&self, reader: &mut impl std::io::BufRead) -> Result, ShellError>; } diff --git a/crates/nu-protocol/src/engine/engine_state.rs b/crates/nu-protocol/src/engine/engine_state.rs index dbded4eb63..5ee560f8f6 100644 --- a/crates/nu-protocol/src/engine/engine_state.rs +++ b/crates/nu-protocol/src/engine/engine_state.rs @@ -609,7 +609,7 @@ impl EngineState { } } - /// Find the [`DeclId`](nu_protocol::id::DeclId) corresponding to a declaration with `name`. + /// Find the [`DeclId`](crate::DeclId) corresponding to a declaration with `name`. /// /// Searches within active overlays, and filtering out overlays in `removed_overlays`. pub fn find_decl(&self, name: &[u8], removed_overlays: &[Vec]) -> Option { @@ -649,21 +649,21 @@ impl EngineState { None } - /// Find the [`OverlayId`](nu_protocol::id::OverlayId) corresponding to `name`. + /// Find the [`OverlayId`](crate::OverlayId) corresponding to `name`. /// /// Searches all overlays, not just active overlays. To search only in active overlays, use [`find_active_overlay`](EngineState::find_active_overlay) pub fn find_overlay(&self, name: &[u8]) -> Option { self.scope.find_overlay(name) } - /// Find the [`OverlayId`](nu_protocol::id::OverlayId) of the active overlay corresponding to `name`. + /// Find the [`OverlayId`](crate::OverlayId) of the active overlay corresponding to `name`. /// /// Searches only active overlays. To search in all overlays, use [`find_overlay`](EngineState::find_active_overlay) pub fn find_active_overlay(&self, name: &[u8]) -> Option { self.scope.find_active_overlay(name) } - /// Find the [`ModuleId`](nu_protocol::id::ModuleId) corresponding to `name`. + /// Find the [`ModuleId`](crate::ModuleId) corresponding to `name`. /// /// Searches within active overlays, and filtering out overlays in `removed_overlays`. pub fn find_module(&self, name: &[u8], removed_overlays: &[Vec]) -> Option { diff --git a/crates/nu-protocol/src/engine/state_working_set.rs b/crates/nu-protocol/src/engine/state_working_set.rs index f9895735b8..441e5350be 100644 --- a/crates/nu-protocol/src/engine/state_working_set.rs +++ b/crates/nu-protocol/src/engine/state_working_set.rs @@ -410,7 +410,7 @@ impl<'a> StateWorkingSet<'a> { self.delta.exit_scope(); } - /// Find the [`DeclId`](nu_protocol::id::DeclId) corresponding to a predeclaration with `name`. + /// Find the [`DeclId`](crate::DeclId) corresponding to a predeclaration with `name`. pub fn find_predecl(&self, name: &[u8]) -> Option { let mut removed_overlays = vec![]; @@ -429,10 +429,11 @@ impl<'a> StateWorkingSet<'a> { None } - /// Find the [`DeclId`](nu_protocol::id::DeclId) corresponding to a declaration with `name`. + /// Find the [`DeclId`](crate::DeclId) corresponding to a declaration with `name`. /// - /// Extends [`EngineState::find_decl`] to also search for predeclarations (if [`StateWorkingSet::search_predecls`] is set), - /// and declarations from scopes existing only in [`StateDelta`]. + /// Extends [`EngineState::find_decl`] to also search for predeclarations + /// (if [`StateWorkingSet::search_predecls`] is set), and declarations from scopes existing + /// only in [`StateDelta`]. pub fn find_decl(&self, name: &[u8]) -> Option { let mut removed_overlays = vec![]; @@ -516,7 +517,7 @@ impl<'a> StateWorkingSet<'a> { .find_decl_name(decl_id, &removed_overlays) } - /// Find the [`ModuleId`](nu_protocol::id::ModuleId) corresponding to `name`. + /// Find the [`ModuleId`](crate::ModuleId) corresponding to `name`. /// /// Extends [`EngineState::find_module`] to also search for , /// and declarations from scopes existing only in [`StateDelta`]. diff --git a/crates/nu-protocol/src/errors/shell_error/io.rs b/crates/nu-protocol/src/errors/shell_error/io.rs index 87eaabc74d..88072ec45e 100644 --- a/crates/nu-protocol/src/errors/shell_error/io.rs +++ b/crates/nu-protocol/src/errors/shell_error/io.rs @@ -256,9 +256,10 @@ impl IoError { /// Creates a new `IoError` for internal I/O errors with a specific path. /// - /// This constructor is similar to [`new_internal`] but also includes a file or directory - /// path relevant to the error. Use this function in rare cases where an internal error - /// involves a specific path, and the combination of path and additional context is helpful. + /// This constructor is similar to [`new_internal`](Self::new_internal) but also includes a + /// file or directory path relevant to the error. + /// Use this function in rare cases where an internal error involves a specific path, and the + /// combination of path and additional context is helpful. /// /// # Examples /// ```rust diff --git a/crates/nu-protocol/src/pipeline/pipeline_data.rs b/crates/nu-protocol/src/pipeline/pipeline_data.rs index b4a1e9ca01..3ccfae4c85 100644 --- a/crates/nu-protocol/src/pipeline/pipeline_data.rs +++ b/crates/nu-protocol/src/pipeline/pipeline_data.rs @@ -126,7 +126,7 @@ impl PipelineData { /// Determine if the `PipelineData` is a [subtype](https://en.wikipedia.org/wiki/Subtyping) of `other`. /// /// This check makes no effort to collect a stream, so it may be a different result - /// than would be returned by calling [`Value::is_subtype()`] on the result of + /// than would be returned by calling [`Value::is_subtype_of()`] on the result of /// [`.into_value()`](Self::into_value). /// /// A `ListStream` acts the same as an empty list type: it is a subtype of any [`list`](Type::List) diff --git a/crates/nu-protocol/src/span.rs b/crates/nu-protocol/src/span.rs index dd465b5a63..77e5bab681 100644 --- a/crates/nu-protocol/src/span.rs +++ b/crates/nu-protocol/src/span.rs @@ -224,8 +224,9 @@ impl From for SourceSpan { /// An extension trait for [`Result`], which adds a span to the error type. /// -/// This trait might be removed later, since the old [`Spanned`] to [`ShellError`] -/// conversion was replaced by [`IoError`](io_error::IoError). +/// This trait might be removed later, since the old [`Spanned`] to +/// [`ShellError`](crate::ShellError) conversion was replaced by +/// [`IoError`](crate::shell_error::io::IoError). pub trait ErrSpan { type Result; diff --git a/crates/nu-protocol/src/ty.rs b/crates/nu-protocol/src/ty.rs index 440bd24475..2308ce1579 100644 --- a/crates/nu-protocol/src/ty.rs +++ b/crates/nu-protocol/src/ty.rs @@ -49,8 +49,9 @@ impl Type { /// Determine of the [`Type`] is a [subtype](https://en.wikipedia.org/wiki/Subtyping) of `other`. /// - /// This should only be used at parse-time. If you have a concrete [`Value`](crate::Value) or [`PipelineData`](crate::PipelineData), - /// you should use their respective [`is_subtype_of`] methods instead. + /// This should only be used at parse-time. + /// If you have a concrete [`Value`](crate::Value) or [`PipelineData`](crate::PipelineData), + /// you should use their respective `is_subtype_of` methods instead. pub fn is_subtype_of(&self, other: &Type) -> bool { // Structural subtyping let is_subtype_collection = |this: &[(String, Type)], that: &[(String, Type)]| { diff --git a/crates/nu-protocol/src/value/mod.rs b/crates/nu-protocol/src/value/mod.rs index 09ec0fb04f..f310055f1e 100644 --- a/crates/nu-protocol/src/value/mod.rs +++ b/crates/nu-protocol/src/value/mod.rs @@ -820,7 +820,7 @@ impl Value { /// This method is able to leverage that information encoded in a `Value` to provide more accurate /// type comparison than if one were to collect the type into [`Type`](crate::Type) value with [`Value::get_type`]. /// - /// Empty lists are considered subtypes of all list types. + /// Empty lists are considered subtypes of all `list` types. /// /// Lists of mixed records where some column is present in all record is a subtype of `table`. /// For example, `[{a: 1, b: 2}, {a: 1}]` is a subtype of `table` (but not `table`).