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.
This commit is contained in:
Devyn Cairns 2024-07-27 19:39:29 -07:00 committed by GitHub
parent d80de68665
commit d618fd0527
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
15 changed files with 40 additions and 37 deletions

View File

@ -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()
}

View File

@ -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")]

View File

@ -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>;

View File

@ -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<bool, ShellError> {
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<StreamData>) -> 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<bool, ShellError> {
let mut state = self.lock()?;
state.unacknowledged =

View File

@ -45,7 +45,7 @@ fn fail_if_poisoned<'a, T>(
}
impl<T: Clone + Send> WaitableMut<T> {
/// 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<T> {
WaitableMut {
shared: Arc::new(WaitableShared {

View File

@ -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);
}

View File

@ -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(),

View File

@ -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<impl Into<String>>, 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<impl Into<String>>) -> Self {
self.add_flag(name);
self

View File

@ -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 {
""
}

View File

@ -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<String>) -> Result<Option<DeclId>, 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<EngineInterface>);
impl ForegroundGuard {

View File

@ -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<Block>> {
self.blocks.get(block_id)
}

View File

@ -51,7 +51,7 @@ pub struct Stack {
pub parent_stack: Option<Arc<Stack>>,
/// Variables that have been deleted (this is used to hide values from parent stack lookups)
pub parent_deletions: Vec<VarId>,
/// Locally updated config. Use [`.get_config()`] to access correctly.
/// Locally updated config. Use [`.get_config()`](Self::get_config) to access correctly.
pub config: Option<Arc<Config>>,
pub(crate) out_dest: StackOutDest,
}

View File

@ -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
///

View File

@ -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),

View File

@ -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
///