From d618fd0527c589ca66ea4c8af813e2bbca32ee88 Mon Sep 17 00:00:00 2001 From: Devyn Cairns Date: Sat, 27 Jul 2024 19:39:29 -0700 Subject: [PATCH] Fix bad method links in docstrings (#13471) # Description Seems like I developed a bit of a bad habit of trying to link ```rust /// [`.foo()`] ``` in docstrings, and this just doesn't work automatically; you have to do ```rust /// [`.foo()`](Self::foo) ``` if you want it to actually link. I think I found and replaced all of these. # User-Facing Changes Just docs. --- crates/nu-engine/src/compile/builder.rs | 2 +- crates/nu-plugin-core/src/communication_mode/mod.rs | 4 ++-- crates/nu-plugin-core/src/interface/mod.rs | 2 +- crates/nu-plugin-core/src/interface/stream/mod.rs | 10 +++++----- crates/nu-plugin-core/src/util/waitable.rs | 2 +- crates/nu-plugin-engine/src/gc.rs | 4 ++-- crates/nu-plugin-engine/src/source.rs | 2 +- crates/nu-plugin-protocol/src/evaluated_call.rs | 6 +++--- crates/nu-plugin/src/plugin/command.rs | 10 +++++----- crates/nu-plugin/src/plugin/interface/mod.rs | 13 +++++++------ crates/nu-protocol/src/engine/engine_state.rs | 6 +++--- crates/nu-protocol/src/engine/stack.rs | 2 +- crates/nu-protocol/src/errors/labeled_error.rs | 3 ++- crates/nu-protocol/src/pipeline/pipeline_data.rs | 3 ++- crates/nu-system/src/foreground.rs | 8 ++++---- 15 files changed, 40 insertions(+), 37 deletions(-) diff --git a/crates/nu-engine/src/compile/builder.rs b/crates/nu-engine/src/compile/builder.rs index 4294b2bd61..2a443b7bde 100644 --- a/crates/nu-engine/src/compile/builder.rs +++ b/crates/nu-engine/src/compile/builder.rs @@ -423,7 +423,7 @@ impl BlockBuilder { self.push(Instruction::Jump { index: label_id.0 }.into_spanned(span)) } - /// The index that the next instruction [`.push()`]ed will have. + /// The index that the next instruction [`.push()`](Self::push)ed will have. pub(crate) fn here(&self) -> usize { self.instructions.len() } diff --git a/crates/nu-plugin-core/src/communication_mode/mod.rs b/crates/nu-plugin-core/src/communication_mode/mod.rs index 1eb72d6ac8..576cfe866c 100644 --- a/crates/nu-plugin-core/src/communication_mode/mod.rs +++ b/crates/nu-plugin-core/src/communication_mode/mod.rs @@ -122,11 +122,11 @@ impl CommunicationMode { /// The result of [`CommunicationMode::serve()`], which acts as an intermediate stage for /// communication modes that require some kind of socket binding to occur before the client process -/// can be started. Call [`.connect()`] once the client process has been started. +/// can be started. Call [`.connect()`](Self::connect) once the client process has been started. /// /// The socket may be cleaned up on `Drop` if applicable. pub enum PreparedServerCommunication { - /// Will take stdin and stdout from the process on [`.connect()`]. + /// Will take stdin and stdout from the process on [`.connect()`](Self::connect). Stdio, /// Contains the listener to accept connections on. On Unix, the socket is unlinked on `Drop`. #[cfg(feature = "local-socket")] diff --git a/crates/nu-plugin-core/src/interface/mod.rs b/crates/nu-plugin-core/src/interface/mod.rs index 89aa2b15e5..d282eddd8b 100644 --- a/crates/nu-plugin-core/src/interface/mod.rs +++ b/crates/nu-plugin-core/src/interface/mod.rs @@ -145,7 +145,7 @@ pub trait InterfaceManager { /// Consume an input message. /// - /// When implementing, call [`.consume_stream_message()`] for any encapsulated + /// When implementing, call [`.consume_stream_message()`](Self::consume_stream_message) for any encapsulated /// [`StreamMessage`]s received. fn consume(&mut self, input: Self::Input) -> Result<(), ShellError>; diff --git a/crates/nu-plugin-core/src/interface/stream/mod.rs b/crates/nu-plugin-core/src/interface/stream/mod.rs index 541e1176a0..cfe44fabb4 100644 --- a/crates/nu-plugin-core/src/interface/stream/mod.rs +++ b/crates/nu-plugin-core/src/interface/stream/mod.rs @@ -189,14 +189,14 @@ where } /// Check if the stream was dropped from the other end. Recommended to do this before calling - /// [`.write()`], especially in a loop. + /// [`.write()`](Self::write), especially in a loop. pub fn is_dropped(&self) -> Result { self.signal.is_dropped() } /// Write a single piece of data to the stream. /// - /// Error if something failed with the write, or if [`.end()`] was already called + /// Error if something failed with the write, or if [`.end()`](Self::end) was already called /// previously. pub fn write(&mut self, data: impl Into) -> Result<(), ShellError> { if !self.ended { @@ -228,7 +228,7 @@ where } /// Write a full iterator to the stream. Note that this doesn't end the stream, so you should - /// still call [`.end()`]. + /// still call [`.end()`](Self::end). /// /// If the stream is dropped from the other end, the iterator will not be fully consumed, and /// writing will terminate. @@ -341,8 +341,8 @@ impl StreamWriterSignal { } /// Track that a message has been sent. Returns `Ok(true)` if more messages can be sent, - /// or `Ok(false)` if the high pressure mark has been reached and [`.wait_for_drain()`] should - /// be called to block. + /// or `Ok(false)` if the high pressure mark has been reached and + /// [`.wait_for_drain()`](Self::wait_for_drain) should be called to block. pub fn notify_sent(&self) -> Result { let mut state = self.lock()?; state.unacknowledged = diff --git a/crates/nu-plugin-core/src/util/waitable.rs b/crates/nu-plugin-core/src/util/waitable.rs index aaefa6f1b5..0f4cb30de3 100644 --- a/crates/nu-plugin-core/src/util/waitable.rs +++ b/crates/nu-plugin-core/src/util/waitable.rs @@ -45,7 +45,7 @@ fn fail_if_poisoned<'a, T>( } impl WaitableMut { - /// Create a new empty `WaitableMut`. Call [`.reader()`] to get [`Waitable`]. + /// Create a new empty `WaitableMut`. Call [`.reader()`](Self::reader) to get [`Waitable`]. pub fn new() -> WaitableMut { WaitableMut { shared: Arc::new(WaitableShared { diff --git a/crates/nu-plugin-engine/src/gc.rs b/crates/nu-plugin-engine/src/gc.rs index bd9c8de06f..555c57e47d 100644 --- a/crates/nu-plugin-engine/src/gc.rs +++ b/crates/nu-plugin-engine/src/gc.rs @@ -80,8 +80,8 @@ impl PluginGc { /// /// The reason the plugin tells the GC rather than just stopping itself via `source` is that /// it can't guarantee that the plugin currently pointed to by `source` is itself, but if the - /// GC is still running, it hasn't received [`.stop_tracking()`] yet, which means it should be - /// the right plugin. + /// GC is still running, it hasn't received [`.stop_tracking()`](Self::stop_tracking) yet, which + /// means it should be the right plugin. pub fn exited(&self) { let _ = self.sender.send(PluginGcMsg::Exited); } diff --git a/crates/nu-plugin-engine/src/source.rs b/crates/nu-plugin-engine/src/source.rs index 9b388576c5..56043eccf5 100644 --- a/crates/nu-plugin-engine/src/source.rs +++ b/crates/nu-plugin-engine/src/source.rs @@ -26,7 +26,7 @@ impl PluginSource { /// Create a new fake source with a fake identity, for testing /// - /// Warning: [`.persistent()`] will always return an error. + /// Warning: [`.persistent()`](Self::persistent) will always return an error. pub fn new_fake(name: &str) -> PluginSource { PluginSource { identity: PluginIdentity::new_fake(name).into(), diff --git a/crates/nu-plugin-protocol/src/evaluated_call.rs b/crates/nu-plugin-protocol/src/evaluated_call.rs index 5e760693a5..c5cbcc5ba0 100644 --- a/crates/nu-plugin-protocol/src/evaluated_call.rs +++ b/crates/nu-plugin-protocol/src/evaluated_call.rs @@ -85,19 +85,19 @@ impl EvaluatedCall { self } - /// Builder variant of [`.add_positional()`]. + /// Builder variant of [`.add_positional()`](Self::add_positional). pub fn with_positional(mut self, value: Value) -> Self { self.add_positional(value); self } - /// Builder variant of [`.add_named()`]. + /// Builder variant of [`.add_named()`](Self::add_named). pub fn with_named(mut self, name: Spanned>, value: Value) -> Self { self.add_named(name, value); self } - /// Builder variant of [`.add_flag()`]. + /// Builder variant of [`.add_flag()`](Self::add_flag). pub fn with_flag(mut self, name: Spanned>) -> Self { self.add_flag(name); self diff --git a/crates/nu-plugin/src/plugin/command.rs b/crates/nu-plugin/src/plugin/command.rs index a90555ac40..8e8adc9578 100644 --- a/crates/nu-plugin/src/plugin/command.rs +++ b/crates/nu-plugin/src/plugin/command.rs @@ -75,8 +75,8 @@ use crate::{EngineInterface, EvaluatedCall, Plugin}; pub trait PluginCommand: Sync { /// The type of plugin this command runs on. /// - /// Since [`.run()`] takes a reference to the plugin, it is necessary to define the type of - /// plugin that the command expects here. + /// Since [`.run()`](Self::run) takes a reference to the plugin, it is necessary to define the + /// type of plugin that the command expects here. type Plugin: Plugin; /// The name of the command from within Nu. @@ -96,9 +96,9 @@ pub trait PluginCommand: Sync { /// Additional documentation for usage of the command. /// - /// This is optional - any arguments documented by [`.signature()`] will be shown in the help - /// page automatically. However, this can be useful for explaining things that would be too - /// brief to include in [`.usage()`] and may span multiple lines. + /// This is optional - any arguments documented by [`.signature()`](Self::signature) will be + /// shown in the help page automatically. However, this can be useful for explaining things that + /// would be too brief to include in [`.usage()`](Self::usage) and may span multiple lines. fn extra_usage(&self) -> &str { "" } diff --git a/crates/nu-plugin/src/plugin/interface/mod.rs b/crates/nu-plugin/src/plugin/interface/mod.rs index c20e2adc39..10f787b222 100644 --- a/crates/nu-plugin/src/plugin/interface/mod.rs +++ b/crates/nu-plugin/src/plugin/interface/mod.rs @@ -618,8 +618,9 @@ impl EngineInterface { /// Get all environment variables from the engine. /// - /// Since this is quite a large map that has to be sent, prefer to use [`.get_env_var()`] if - /// the variables needed are known ahead of time and there are only a small number needed. + /// Since this is quite a large map that has to be sent, prefer to use + /// [`.get_env_var()`] (Self::get_env_var) if the variables needed are known ahead of time + /// and there are only a small number needed. /// /// # Example /// ```rust,no_run @@ -873,9 +874,9 @@ impl EngineInterface { } /// Ask the engine for the identifier for a declaration. If found, the result can then be passed - /// to [`.call_decl()`] to call other internal commands. + /// to [`.call_decl()`](Self::call_decl) to call other internal commands. /// - /// See [`.call_decl()`] for an example. + /// See [`.call_decl()`](Self::call_decl) for an example. pub fn find_decl(&self, name: impl Into) -> Result, ShellError> { let call = EngineCall::FindDecl(name.into()); @@ -890,7 +891,7 @@ impl EngineInterface { } /// Ask the engine to call an internal command, using the declaration ID previously looked up - /// with [`.find_decl()`]. + /// with [`.find_decl()`](Self::find_decl). /// /// # Example /// @@ -1008,7 +1009,7 @@ impl Interface for EngineInterface { /// Keeps the plugin in the foreground as long as it is alive. /// -/// Use [`.leave()`] to leave the foreground without ignoring the error. +/// Use [`.leave()`](Self::leave) to leave the foreground without ignoring the error. pub struct ForegroundGuard(Option); impl ForegroundGuard { diff --git a/crates/nu-protocol/src/engine/engine_state.rs b/crates/nu-protocol/src/engine/engine_state.rs index fce24cebbd..8579295c32 100644 --- a/crates/nu-protocol/src/engine/engine_state.rs +++ b/crates/nu-protocol/src/engine/engine_state.rs @@ -832,9 +832,9 @@ impl EngineState { /// Optionally get a block by id, if it exists /// - /// Prefer to use [`.get_block()`] in most cases - `BlockId`s that don't exist are normally a - /// compiler error. This only exists to stop plugins from crashing the engine if they send us - /// something invalid. + /// Prefer to use [`.get_block()`](Self::get_block) in most cases - `BlockId`s that don't exist + /// are normally a compiler error. This only exists to stop plugins from crashing the engine if + /// they send us something invalid. pub fn try_get_block(&self, block_id: BlockId) -> Option<&Arc> { self.blocks.get(block_id) } diff --git a/crates/nu-protocol/src/engine/stack.rs b/crates/nu-protocol/src/engine/stack.rs index fbfb586762..7ba8268985 100644 --- a/crates/nu-protocol/src/engine/stack.rs +++ b/crates/nu-protocol/src/engine/stack.rs @@ -51,7 +51,7 @@ pub struct Stack { pub parent_stack: Option>, /// Variables that have been deleted (this is used to hide values from parent stack lookups) pub parent_deletions: Vec, - /// Locally updated config. Use [`.get_config()`] to access correctly. + /// Locally updated config. Use [`.get_config()`](Self::get_config) to access correctly. pub config: Option>, pub(crate) out_dest: StackOutDest, } diff --git a/crates/nu-protocol/src/errors/labeled_error.rs b/crates/nu-protocol/src/errors/labeled_error.rs index 20ac9cff71..c76a6c78dd 100644 --- a/crates/nu-protocol/src/errors/labeled_error.rs +++ b/crates/nu-protocol/src/errors/labeled_error.rs @@ -37,7 +37,8 @@ pub struct LabeledError { impl LabeledError { /// Create a new plain [`LabeledError`] with the given message. /// - /// This is usually used builder-style with methods like [`.with_label()`] to build an error. + /// This is usually used builder-style with methods like [`.with_label()`](Self::with_label) to + /// build an error. /// /// # Example /// diff --git a/crates/nu-protocol/src/pipeline/pipeline_data.rs b/crates/nu-protocol/src/pipeline/pipeline_data.rs index 0d1c0b3092..2ae8027f06 100644 --- a/crates/nu-protocol/src/pipeline/pipeline_data.rs +++ b/crates/nu-protocol/src/pipeline/pipeline_data.rs @@ -117,7 +117,8 @@ impl PipelineData { /// Get a type that is representative of the `PipelineData`. /// /// The type returned here makes no effort to collect a stream, so it may be a different type - /// than would be returned by [`Value::get_type()`] on the result of [`.into_value()`]. + /// than would be returned by [`Value::get_type()`] on the result of + /// [`.into_value()`](Self::into_value). /// /// Specifically, a `ListStream` results in [`list stream`](Type::ListStream) rather than /// the fully complete [`list`](Type::List) type (which would require knowing the contents), diff --git a/crates/nu-system/src/foreground.rs b/crates/nu-system/src/foreground.rs index 2fe3c4fb29..bd78f616aa 100644 --- a/crates/nu-system/src/foreground.rs +++ b/crates/nu-system/src/foreground.rs @@ -105,10 +105,10 @@ impl Drop for ForegroundChild { /// /// If there is already a foreground external process running, spawned with [`ForegroundChild`], /// this expects the process ID to remain in the process group created by the [`ForegroundChild`] -/// for the lifetime of the guard, and keeps the terminal controlling process group set to that. If -/// there is no foreground external process running, this sets the foreground process group to the -/// plugin's process ID. The process group that is expected can be retrieved with [`.pgrp()`] if -/// different from the plugin process ID. +/// for the lifetime of the guard, and keeps the terminal controlling process group set to that. +/// If there is no foreground external process running, this sets the foreground process group to +/// the plugin's process ID. The process group that is expected can be retrieved with +/// [`.pgrp()`](Self::pgrp) if different from the plugin process ID. /// /// ## Other systems ///