From ff41cf91ef06c0bc3fbb8f61ec5ddd3dd175fef7 Mon Sep 17 00:00:00 2001 From: Devyn Cairns Date: Sat, 23 Mar 2024 05:26:08 -0700 Subject: [PATCH] Misc doc fixes (#12266) # Description Just a bunch of miscellaneous fixes to the Rust documentation that I found recently while doing a pass on some things. # User-Facing Changes None --- crates/nu-command/src/charting/hashable_value.rs | 10 ++++++---- crates/nu-explore/src/explore.rs | 2 +- crates/nu-path/src/expansions.rs | 2 +- crates/nu-plugin/src/lib.rs | 4 ++-- crates/nu-plugin/src/plugin/command.rs | 11 ++++++----- crates/nu-plugin/src/plugin/mod.rs | 8 ++++---- crates/nu-plugin/src/protocol/evaluated_call.rs | 4 ++-- crates/nu-plugin/src/protocol/mod.rs | 4 ++-- crates/nu-protocol/src/pipeline_data/io_stream.rs | 3 ++- crates/nu-protocol/src/pipeline_data/mod.rs | 2 +- crates/nu-protocol/src/plugin/registered.rs | 2 +- crates/nu-protocol/src/value/custom_value.rs | 3 +-- crates/nu-table/src/table.rs | 2 +- src/tests/test_config_path.rs | 4 ++-- 14 files changed, 32 insertions(+), 29 deletions(-) diff --git a/crates/nu-command/src/charting/hashable_value.rs b/crates/nu-command/src/charting/hashable_value.rs index dda79f2ceb..5b49a3fcd2 100644 --- a/crates/nu-command/src/charting/hashable_value.rs +++ b/crates/nu-command/src/charting/hashable_value.rs @@ -2,11 +2,13 @@ use chrono::{DateTime, FixedOffset}; use nu_protocol::{ShellError, Span, Value}; use std::hash::{Hash, Hasher}; -/// A subset of [Value](crate::Value), which is hashable. -/// And it means that we can put the value into something like [HashMap](std::collections::HashMap) or [HashSet](std::collections::HashSet) -/// for further usage like value statistics. +/// A subset of [`Value`](crate::Value), which is hashable. +/// And it means that we can put the value into something like +/// [`HashMap`](std::collections::HashMap) or [`HashSet`](std::collections::HashSet) for further +/// usage like value statistics. /// -/// For now the main way to crate a [HashableValue] is using [from_value](HashableValue::from_value) +/// For now the main way to crate a [`HashableValue`] is using +/// [`from_value`](HashableValue::from_value) /// /// Please note that although each variant contains `span` field, but during hashing, this field will not be concerned. /// Which means that the following will be true: diff --git a/crates/nu-explore/src/explore.rs b/crates/nu-explore/src/explore.rs index decfa1f389..d572068314 100644 --- a/crates/nu-explore/src/explore.rs +++ b/crates/nu-explore/src/explore.rs @@ -13,7 +13,7 @@ use nu_protocol::{ }; use std::collections::HashMap; -/// A `less` like program to render a [Value] as a table. +/// A `less` like program to render a [`Value`] as a table. #[derive(Clone)] pub struct Explore; diff --git a/crates/nu-path/src/expansions.rs b/crates/nu-path/src/expansions.rs index fc5eeea5fa..e044254dc5 100644 --- a/crates/nu-path/src/expansions.rs +++ b/crates/nu-path/src/expansions.rs @@ -38,7 +38,7 @@ fn canonicalize(path: impl AsRef) -> io::Result { /// absolute form. /// /// Fails under the same conditions as -/// [std::fs::canonicalize](https://doc.rust-lang.org/std/fs/fn.canonicalize.html). +/// [`std::fs::canonicalize`](https://doc.rust-lang.org/std/fs/fn.canonicalize.html). /// The input path is specified relative to another path pub fn canonicalize_with(path: P, relative_to: Q) -> io::Result where diff --git a/crates/nu-plugin/src/lib.rs b/crates/nu-plugin/src/lib.rs index df139529f6..e1a79104a8 100644 --- a/crates/nu-plugin/src/lib.rs +++ b/crates/nu-plugin/src/lib.rs @@ -10,8 +10,8 @@ //! over stdin and stdout using a standardizes serialization framework to exchange //! the typed data that Nushell commands utilize natively. //! -//! A typical plugin application will define a struct that implements the [Plugin] -//! trait and then, in it's main method, pass that [Plugin] to the [serve_plugin] +//! A typical plugin application will define a struct that implements the [`Plugin`] +//! trait and then, in its main method, pass that [`Plugin`] to the [`serve_plugin()`] //! function, which will handle all of the input and output serialization when //! invoked by Nushell. //! diff --git a/crates/nu-plugin/src/plugin/command.rs b/crates/nu-plugin/src/plugin/command.rs index 06014877d6..4e82056d35 100644 --- a/crates/nu-plugin/src/plugin/command.rs +++ b/crates/nu-plugin/src/plugin/command.rs @@ -5,7 +5,8 @@ use crate::{EngineInterface, EvaluatedCall, Plugin}; /// The API for a Nushell plugin command /// /// This is the trait that Nushell plugin commands must implement. The methods defined on -/// `PluginCommand` are invoked by [serve_plugin] during plugin registration and execution. +/// `PluginCommand` are invoked by [`serve_plugin`](crate::serve_plugin) during plugin registration +/// and execution. /// /// The plugin command must be able to be safely shared between threads, so that multiple /// invocations can be run in parallel. If interior mutability is desired, consider synchronization @@ -73,8 +74,8 @@ pub trait PluginCommand: Sync { /// Perform the actual behavior of the plugin command /// /// The behavior of the plugin is defined by the implementation of this method. When Nushell - /// invoked the plugin [serve_plugin] will call this method and print the serialized returned - /// value or error to stdout, which Nushell will interpret. + /// invoked the plugin [`serve_plugin`](crate::serve_plugin) will call this method and print the + /// serialized returned value or error to stdout, which Nushell will interpret. /// /// `engine` provides an interface back to the Nushell engine. See [`EngineInterface`] docs for /// details on what methods are available. @@ -156,8 +157,8 @@ pub trait SimplePluginCommand: Sync { /// Perform the actual behavior of the plugin command /// /// The behavior of the plugin is defined by the implementation of this method. When Nushell - /// invoked the plugin [serve_plugin] will call this method and print the serialized returned - /// value or error to stdout, which Nushell will interpret. + /// invoked the plugin [`serve_plugin`](crate::serve_plugin) will call this method and print the + /// serialized returned value or error to stdout, which Nushell will interpret. /// /// `engine` provides an interface back to the Nushell engine. See [`EngineInterface`] docs for /// details on what methods are available. diff --git a/crates/nu-plugin/src/plugin/mod.rs b/crates/nu-plugin/src/plugin/mod.rs index acb92a9016..deda34c931 100644 --- a/crates/nu-plugin/src/plugin/mod.rs +++ b/crates/nu-plugin/src/plugin/mod.rs @@ -57,8 +57,8 @@ pub(crate) const OUTPUT_BUFFER_SIZE: usize = 8192; pub trait Encoder: Clone + Send + Sync { /// Serialize a value in the [`PluginEncoder`]s format /// - /// Returns [ShellError::IOError] if there was a problem writing, or - /// [ShellError::PluginFailedToEncode] for a serialization error. + /// Returns [`ShellError::IOError`] if there was a problem writing, or + /// [`ShellError::PluginFailedToEncode`] for a serialization error. #[doc(hidden)] fn encode(&self, data: &T, writer: &mut impl std::io::Write) -> Result<(), ShellError>; @@ -66,8 +66,8 @@ 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 - /// [ShellError::PluginFailedToDecode] for a deserialization error. + /// Returns [`ShellError::IOError`] if there was a problem reading, or + /// [`ShellError::PluginFailedToDecode`] for a deserialization error. #[doc(hidden)] fn decode(&self, reader: &mut impl std::io::BufRead) -> Result, ShellError>; } diff --git a/crates/nu-plugin/src/protocol/evaluated_call.rs b/crates/nu-plugin/src/protocol/evaluated_call.rs index f2f9df0cc9..5f96aeba58 100644 --- a/crates/nu-plugin/src/protocol/evaluated_call.rs +++ b/crates/nu-plugin/src/protocol/evaluated_call.rs @@ -9,9 +9,9 @@ use serde::{Deserialize, Serialize}; /// A representation of the plugin's invocation command including command line args /// -/// The `EvaluatedCall` contains information about the way a [Plugin](crate::Plugin) was invoked +/// The `EvaluatedCall` contains information about the way a [`Plugin`](crate::Plugin) was invoked /// representing the [`Span`] corresponding to the invocation as well as the arguments -/// it was invoked with. It is one of three items passed to [`run`](crate::Plugin::run()) along with +/// it was invoked with. It is one of three items passed to [`run()`](crate::PluginCommand::run()) along with /// `name` which command that was invoked and a [`Value`] that represents the input. /// /// The evaluated call is used with the Plugins because the plugin doesn't have diff --git a/crates/nu-plugin/src/protocol/mod.rs b/crates/nu-plugin/src/protocol/mod.rs index 9ae3fe80d9..165f76540e 100644 --- a/crates/nu-plugin/src/protocol/mod.rs +++ b/crates/nu-plugin/src/protocol/mod.rs @@ -353,7 +353,7 @@ pub enum PluginOption { GcDisabled(bool), } -/// This is just a serializable version of [std::cmp::Ordering], and can be converted 1:1 +/// This is just a serializable version of [`std::cmp::Ordering`], and can be converted 1:1 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)] pub enum Ordering { Less, @@ -505,7 +505,7 @@ impl EngineCall { } } -/// The response to an [EngineCall]. The type parameter determines the output type for pipeline +/// The response to an [`EngineCall`]. The type parameter determines the output type for pipeline /// data. #[derive(Serialize, Deserialize, Debug, Clone)] pub enum EngineCallResponse { diff --git a/crates/nu-protocol/src/pipeline_data/io_stream.rs b/crates/nu-protocol/src/pipeline_data/io_stream.rs index b6c95d4eb9..57cfd02020 100644 --- a/crates/nu-protocol/src/pipeline_data/io_stream.rs +++ b/crates/nu-protocol/src/pipeline_data/io_stream.rs @@ -9,7 +9,8 @@ pub enum IoStream { /// If both `stdout` and `stderr` are set to `Pipe`, /// then they will combined into `ExternalStream::stdout`. Pipe, - /// Capture output to later be collected into a [`Value`], `Vec`, or used in some other way. + /// Capture output to later be collected into a [`Value`](crate::Value), `Vec`, or used in some + /// other way. /// /// The output stream(s) will be available in /// `PipelineData::ExternalStream::stdout` or `PipelineData::ExternalStream::stderr`. diff --git a/crates/nu-protocol/src/pipeline_data/mod.rs b/crates/nu-protocol/src/pipeline_data/mod.rs index f0c938ebc2..49ea720713 100644 --- a/crates/nu-protocol/src/pipeline_data/mod.rs +++ b/crates/nu-protocol/src/pipeline_data/mod.rs @@ -876,7 +876,7 @@ impl PipelineData { /// Consume and print self data immediately. /// - /// Unlike [print] does not call `table` to format data and just prints it + /// Unlike [`.print()`] does not call `table` to format data and just prints it /// one element on a line /// * `no_newline` controls if we need to attach newline character to output. /// * `to_stderr` controls if data is output to stderr, when the value is false, the data is output to stdout. diff --git a/crates/nu-protocol/src/plugin/registered.rs b/crates/nu-protocol/src/plugin/registered.rs index 2269ecef03..cb0c893728 100644 --- a/crates/nu-protocol/src/plugin/registered.rs +++ b/crates/nu-protocol/src/plugin/registered.rs @@ -2,7 +2,7 @@ use std::{any::Any, sync::Arc}; use crate::{PluginGcConfig, PluginIdentity, ShellError}; -/// Trait for plugins registered in the [`EngineState`](crate::EngineState). +/// Trait for plugins registered in the [`EngineState`](crate::engine::EngineState). pub trait RegisteredPlugin: Send + Sync { /// The identity of the plugin - its filename, shell, and friendly name. fn identity(&self) -> &PluginIdentity; diff --git a/crates/nu-protocol/src/value/custom_value.rs b/crates/nu-protocol/src/value/custom_value.rs index 797d4f3045..a500753a0b 100644 --- a/crates/nu-protocol/src/value/custom_value.rs +++ b/crates/nu-protocol/src/value/custom_value.rs @@ -80,8 +80,7 @@ pub trait CustomValue: fmt::Debug + Send + Sync { /// For custom values in plugins: return `true` here if you would like to be notified when all /// copies of this custom value are dropped in the engine. /// - /// The notification will take place via - /// [`.custom_value_dropped()`](crate::Plugin::custom_value_dropped) on the plugin. + /// The notification will take place via `custom_value_dropped()` on the plugin type. /// /// The default is `false`. fn notify_plugin_on_drop(&self) -> bool { diff --git a/crates/nu-table/src/table.rs b/crates/nu-table/src/table.rs index 6a41a77c37..0c8754fec0 100644 --- a/crates/nu-table/src/table.rs +++ b/crates/nu-table/src/table.rs @@ -54,7 +54,7 @@ struct Alignments { } impl NuTable { - /// Creates an empty [Table] instance. + /// Creates an empty [`NuTable`] instance. pub fn new(count_rows: usize, count_columns: usize) -> Self { Self { data: VecRecords::new(vec![vec![CellInfo::default(); count_columns]; count_rows]), diff --git a/src/tests/test_config_path.rs b/src/tests/test_config_path.rs index 86a2ccf79e..19a6ff7b64 100644 --- a/src/tests/test_config_path.rs +++ b/src/tests/test_config_path.rs @@ -126,7 +126,7 @@ fn test_default_symlinked_config_path_empty() { }); } -/// Like [[test_default_symlinked_config_path_empty]], but fill the temporary folder +/// Like [`test_default_symlinked_config_path_empty`], but fill the temporary folder /// with broken symlinks and see if they're properly canonicalized #[test] fn test_default_symlink_config_path_broken_symlink_config_files() { @@ -162,7 +162,7 @@ fn test_default_symlink_config_path_broken_symlink_config_files() { ); } -/// Like [[test_default_symlinked_config_path_empty]], but fill the temporary folder +/// Like [`test_default_symlinked_config_path_empty`], but fill the temporary folder /// with working symlinks to empty files and see if they're properly canonicalized #[test] fn test_default_config_path_symlinked_config_files() {