Fix all current rustdoc warnings (apart from mentioning private items)

src/ast.rs

@@ -1582,7 +1582,7 @@ impl ConcreteNodeMut for IfStatement {
 #[derive(Default, Debug)]
 pub struct CaseItem {
     parent: Option<*const dyn Node>,
-    /// case <arguments> ; body
+    /// case \<arguments\> ; body
     pub kw_case: KeywordCase,
     pub arguments: ArgumentList,
     pub semi_nl: SemiNl,
@@ -1615,7 +1615,7 @@ impl CheckParse for CaseItem {
 #[derive(Default, Debug)]
 pub struct SwitchStatement {
     parent: Option<*const dyn Node>,
-    /// switch <argument> ; body ; end args_redirs
+    /// switch \<argument\> ; body ; end args_redirs
     pub kw_switch: KeywordSwitch,
     pub argument: Argument,
     pub semi_nl: SemiNl,

src/common.rs

@@ -1069,7 +1069,8 @@ pub static PROGRAM_NAME: OnceCell<&'static wstr> = OnceCell::new();
 /// MS Windows tty devices do not currently have either a read or write timestamp - those respective
 /// fields of `struct stat` are always set to the current time, which means we can't rely on them.
 /// In this case, we assume no external program has written to the terminal behind our back, making
-/// the multiline prompt usable. See #2859 and https://github.com/Microsoft/BashOnWindows/issues/545
+/// the multiline prompt usable. See [#2859](https://github.com/fish-shell/fish-shell/issues/2859)
+/// and <https://github.com/Microsoft/BashOnWindows/issues/545>
 pub fn has_working_tty_timestamps() -> bool {
     if cfg!(target_os = "windows") {
         false
@@ -1523,7 +1524,7 @@ pub enum WSL {
 /// Determines if we are running under Microsoft's Windows Subsystem for Linux to work around
 /// some known limitations and/or bugs.
 ///
-/// See https://github.com/Microsoft/WSL/issues/423 and Microsoft/WSL#2997
+/// See <https://github.com/Microsoft/WSL/issues/423> and [Microsoft/WSL#2997](https://github.com/Microsoft/WSL/issues/2997)
 #[inline(always)]
 #[cfg(not(target_os = "linux"))]
 pub fn is_windows_subsystem_for_linux(_: WSL) -> bool {
@@ -1533,7 +1534,7 @@ pub fn is_windows_subsystem_for_linux(_: WSL) -> bool {
 /// Determines if we are running under Microsoft's Windows Subsystem for Linux to work around
 /// some known limitations and/or bugs.
 ///
-/// See https://github.com/Microsoft/WSL/issues/423 and Microsoft/WSL#2997
+/// See <https://github.com/Microsoft/WSL/issues/423> and [Microsoft/WSL#2997](https://github.com/Microsoft/WSL/issues/2997)
 #[cfg(target_os = "linux")]
 pub fn is_windows_subsystem_for_linux(v: WSL) -> bool {
     use std::sync::OnceLock;
@@ -1935,7 +1936,7 @@ pub fn is_console_session() -> bool {
     })
 }
 
-/// Asserts that a slice is alphabetically sorted by a [`&wstr`] `name` field.
+/// Asserts that a slice is alphabetically sorted by a <code>&[wstr]</code> `name` field.
 ///
 /// Mainly useful for static asserts/const eval.
 ///

src/env/environment.rs

@@ -403,7 +403,7 @@ impl Environment for EnvScoped {
     }
 }
 
-/// Necessary for Arc<EnvStack> to be sync.
+/// Necessary for [`Arc<EnvStack>`] to be sync.
 /// Safety: again, the global lock.
 unsafe impl Send for EnvStack {}
 

src/env_dispatch.rs

@@ -151,7 +151,7 @@ fn handle_timezone(var_name: &wstr, vars: &EnvStack) {
     }
 }
 
-/// Update the value of [`FISH_EMOJI_WIDTH`].
+/// Update the value of [`FISH_EMOJI_WIDTH`](crate::fallback::FISH_EMOJI_WIDTH).
 fn guess_emoji_width(vars: &EnvStack) {
     use crate::fallback::FISH_EMOJI_WIDTH;
 

src/fallback.rs

@@ -22,7 +22,7 @@ pub static FISH_AMBIGUOUS_WIDTH: AtomicIsize = AtomicIsize::new(1);
 /// This must be configurable because the value changed between Unicode 8 and Unicode 9, `wcwidth()`
 /// is emoji-unaware, and terminal emulators do different things.
 ///
-/// See issues like #4539 and https://github.com/neovim/issues/4976 for how painful this is.
+/// See issues like [#4539](https://github.com/fish-shell/fish-shell/issues/4539) and <https://github.com/neovim/neovim/issues/4976> for how painful this is.
 ///
 /// Valid values are 1, and 2. 1 is the typical emoji width used in Unicode 8 while some newer
 /// terminals use a width of 2 since Unicode 9.

src/fd_monitor.rs

@@ -187,7 +187,7 @@ pub struct FdMonitorItem {
 
 impl FdMonitorItem {
     /// Invoke this item's callback because the fd is readable.
-    /// Returns the [`ItemAction`] to indicate whether the item should be removed from the [`FdMonitor`] set.
+    /// If the given fd is closed, it will be removed from the [`FdMonitor`] set.
     fn service(&mut self) {
         (self.callback)(&mut self.fd)
     }

src/history.rs

@@ -1246,7 +1246,7 @@ impl HistoryImpl {
     }
 
     /// Let indexes be a list of one-based indexes into the history, matching the interpretation of
-    /// $history. That is, $history[1] is the most recently executed command. Values less than one
+    /// `$history`. That is, `$history[1]` is the most recently executed command. Values less than one
     /// are skipped. Return a mapping from index to history item text.
     fn items_at_indexes(
         &mut self,

src/input_common.rs

@@ -678,7 +678,7 @@ pub trait InputEventQueuer {
         }
     }
 
-    /// Function used by [`input_readch`] to read bytes from stdin until enough bytes have been read to
+    /// Function used by [`readch`](Self::readch) to read bytes from stdin until enough bytes have been read to
     /// convert them to a wchar_t. Conversion is done using `mbrtowc`. If a character has previously
     /// been read and then 'unread', that character is returned.
     ///

src/job_group.rs

@@ -71,7 +71,7 @@ pub struct JobGroup {
     wants_term: bool,
     /// Whether we are in the foreground, meaning the user is waiting for this job to complete.
     pub is_foreground: RelaxedAtomicBool,
-    /// The pgid leading our group. This is only ever set if [`job_control`](Self::JobControl) is
+    /// The pgid leading our group. This is only ever set if [`job_control`](Self::job_control) is
     /// true. We ensure the value (when set) is always non-negative and non-zero.
     pgid: AtomicPid,
     /// The original command which produced this job tree.

src/lib.rs

@@ -3,6 +3,7 @@
 #![allow(non_upper_case_globals)]
 #![allow(unknown_lints)]
 #![allow(unstable_name_collisions)]
+#![allow(rustdoc::private_intra_doc_links)]
 #![allow(clippy::assigning_clones)]
 #![allow(clippy::bool_assert_comparison)]
 #![allow(clippy::collapsible_if)]

src/proc.rs

@@ -582,13 +582,13 @@ impl AtomicPid {
 /// represents it. Shellscript functions, builtins and blocks of code may all need to spawn an
 /// external process that handles the piping and redirecting of IO for them.
 ///
-/// If the process is of type process_type_t::external or process_type_t::exec, argv is the argument
-/// array and actual_cmd is the absolute path of the command to execute.
+/// If the process is of type [`ProcessType::external`] or [`ProcessType::exec`], `argv` is the argument
+/// array and `actual_cmd` is the absolute path of the command to execute.
 ///
-/// If the process is of type process_type_t::builtin, argv is the argument vector, and argv[0] is
+/// If the process is of type [`ProcessType::builtin`], `argv` is the argument vector, and `argv[0]` is
 /// the name of the builtin command.
 ///
-/// If the process is of type process_type_t::function, argv is the argument vector, and argv[0] is
+/// If the process is of type [`ProcessType::function`], `argv` is the argument vector, and `argv[0]` is
 /// the name of the shellscript function.
 #[derive(Default)]
 pub struct Process {
@@ -693,17 +693,17 @@ impl Process {
         assert!(old.is_none(), "Process::set_pid() called more than once!");
     }
 
-    /// Sets argv.
+    /// Sets `argv`.
     pub fn set_argv(&mut self, argv: Vec<WString>) {
         self.argv = argv;
     }
 
-    /// Returns argv.
+    /// Returns `argv`.
     pub fn argv(&self) -> &Vec<WString> {
         &self.argv
     }
 
-    /// Returns argv[0].
+    /// Returns `argv[0]`.
     pub fn argv0(&self) -> Option<&wstr> {
         self.argv.get(0).map(|s| s.as_utfstr())
     }

src/screen.rs

@@ -1680,8 +1680,8 @@ fn is_screen_name_escape_seq(code: &wstr) -> Option<usize> {
 
 /// Operating System Command (OSC) escape codes, used by iTerm2 and others:
 /// ESC followed by ], terminated by either BEL or escape + backslash.
-/// See https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
-/// and https://iterm2.com/documentation-escape-codes.html .
+/// See <https://invisible-island.net/xterm/ctlseqs/ctlseqs.html>
+/// and <https://iterm2.com/documentation-escape-codes.html>.
 fn is_osc_escape_seq(code: &wstr) -> Option<usize> {
     if code.char_at(1) == ']' {
         // Start at 2 to skip over <esc>].
@@ -1698,7 +1698,7 @@ fn is_osc_escape_seq(code: &wstr) -> Option<usize> {
     None
 }
 
-/// Generic VT100 three byte sequence: CSI followed by something in the range @ through _.
+/// Generic VT100 three byte sequence: `CSI` followed by something in the range @ through _.
 fn is_three_byte_escape_seq(code: &wstr) -> Option<usize> {
     if code.char_at(1) == '[' && (code.char_at(2) >= '@' && code.char_at(2) <= '_') {
         return Some(3);
@@ -1706,7 +1706,7 @@ fn is_three_byte_escape_seq(code: &wstr) -> Option<usize> {
     None
 }
 
-/// Generic VT100 two byte sequence: <esc> followed by something in the range @ through _.
+/// Generic VT100 two byte sequence: `<esc>` followed by something in the range @ through _.
 fn is_two_byte_escape_seq(code: &wstr) -> Option<usize> {
     if code.char_at(1) >= '@' && code.char_at(1) <= '_' {
         return Some(2);
@@ -1714,8 +1714,8 @@ fn is_two_byte_escape_seq(code: &wstr) -> Option<usize> {
     None
 }
 
-/// Generic VT100 CSI-style sequence. <esc>, followed by zero or more ASCII characters NOT in
-/// the range [@,_], followed by one character in that range.
+/// Generic VT100 CSI-style sequence. `<esc>`, followed by zero or more ASCII characters NOT in
+/// the range `[@,_],` followed by one character in that range.
 /// This will also catch color sequences.
 fn is_csi_style_escape_seq(code: &wstr) -> Option<usize> {
     if code.char_at(1) != '[' {

src/terminal.rs

@@ -17,7 +17,7 @@ use std::sync::Mutex;
 /// remain an `Option` instead of returning `Term` by default and just panicking if [`term()`] was
 /// called before `setup()`.
 ///
-/// We can't just use an AtomicPtr<Arc<Term>> here because there's a race condition when the old Arc
+/// We can't just use an [`AtomicPtr<Arc<Term>>`](std::sync::atomic::AtomicPtr) here because there's a race condition when the old Arc
 /// gets dropped - we would obtain the current (non-null) value of `TERM` in [`term()`] but there's
 /// no guarantee that a simultaneous call to [`setup()`] won't result in this refcount being
 /// decremented to zero and the memory being reclaimed before we can clone it, since we can only
@@ -25,7 +25,7 @@ use std::sync::Mutex;
 pub static TERM: Mutex<Option<Arc<Term>>> = Mutex::new(None);
 
 /// Returns a reference to the global [`Term`] singleton or `None` if not preceded by a successful
-/// call to [`terminal::setup()`].
+/// call to [`terminal::setup()`](setup).
 pub fn term() -> Option<Arc<Term>> {
     TERM.lock()
         .expect("Mutex poisoned!")

src/threads.rs

@@ -553,7 +553,7 @@ pub struct Debounce {
 /// The data shared between [`Debounce`] instances.
 struct DebounceData {
     /// The (one or none) next enqueued request, overwritten each time a new call to
-    /// [`perform()`](Self::perform) is made.
+    /// [`Debounce::perform()`] is made.
     next_req: Option<WorkItem>,
     /// The non-zero token of the current non-abandoned thread or `None` if no thread is running.
     active_token: Option<NonZeroU64>,
@@ -609,9 +609,9 @@ impl Debounce {
         self.perform_with_completion(handler, |_ctx, _result| ())
     }
 
-    /// Enqueue `handler` to be performed on a background thread with [`Completion`] `completion`
-    /// to be performed on the main thread. If a function is already enqueued, this overwrites it
-    /// and that function will not be executed.
+    /// Enqueue `handler` to be performed on a background thread with `completion` to be performed
+    /// on the main thread. If a function is already enqueued, this overwrites it and that function
+    /// will not be executed.
     ///
     /// If the function executes within the optional timeout then `completion` will be invoked on
     /// the main thread with the result of the evaluated `handler`.

src/tinyexpr.rs

@@ -630,7 +630,7 @@ impl<'s> State<'s> {
         }
     }
 
-    /// <power>  = {("-" | "+")} <base>
+    /// \<power\>  = {("-" | "+")} \<base\>
     fn power(&mut self) -> f64 {
         let mut sign = 1.0;
         while let Token::Infix(op) = self.current {
@@ -647,7 +647,7 @@ impl<'s> State<'s> {
         sign * self.base()
     }
 
-    /// <factor> = <power> {"^" <power>}
+    /// \<factor\> = \<power\> {"^" \<power\>}
     fn factor(&mut self) -> f64 {
         let mut ret = self.power();
 
@@ -659,7 +659,7 @@ impl<'s> State<'s> {
         ret
     }
 
-    /// <term>   = <factor> {("*" | "/" | "%") <factor>}
+    /// \<term\>   = \<factor\> {("*" | "/" | "%") \<factor\>}
     fn term(&mut self) -> f64 {
         let mut ret = self.factor();
         while let Token::Infix(op @ (Operator::Mul | Operator::Div | Operator::Rem)) = self.current
@@ -678,7 +678,7 @@ impl<'s> State<'s> {
         ret
     }
 
-    /// <expr>   = <term> {("+" | "-") <term>}
+    /// \<expr\>   = \<term\> {("+" | "-") \<term\>}
     fn expr(&mut self) -> f64 {
         let mut ret = self.term();
         while let Token::Infix(op @ (Operator::Add | Operator::Sub)) = self.current {

src/wchar.rs

@@ -35,7 +35,7 @@ pub use L;
 /// as a UTF-32 character, printing them would result in several characters instead of one UTF-8
 /// character.
 ///
-/// See https://github.com/fish-shell/fish-shell/issues/1894.
+/// See <https://github.com/fish-shell/fish-shell/issues/1894>.
 pub fn encode_byte_to_char(byte: u8) -> char {
     char::from_u32(u32::from(ENCODE_DIRECT_BASE) + u32::from(byte))
         .expect("private-use codepoint should be valid char")

src/wcstringutil.rs

@@ -401,7 +401,7 @@ pub fn split_string_tok<'val>(
 }
 
 /// Joins strings with a separator.
-/// This supports both &[&wstr] and &[&WString].
+/// This supports both <code>&[&[wstr]]</code> and <code>&[&[WString]]</code>
 pub fn join_strings<S: AsRef<wstr>>(strs: &[S], sep: char) -> WString {
     if strs.is_empty() {
         return WString::new();

src/wgetopt.rs

@@ -89,7 +89,7 @@ pub const fn wopt(name: &wstr, arg_type: ArgType, val: char) -> WOption<'_> {
     }
 }
 
-/// Used internally by [Wgetopter::find_matching_long_opt]. See there for further
+/// Used internally by [WGetopter::find_matching_long_opt]. See there for further
 /// details.
 #[derive(Default)]
 enum LongOptMatch<'a> {
@@ -100,7 +100,7 @@ enum LongOptMatch<'a> {
     NoMatch,
 }
 
-/// Used internally by [Wgetopter::next_argv]. See there for further details.
+/// Used internally by [WGetopter::next_argv]. See there for further details.
 enum NextArgv {
     Finished,
     UnpermutedNonOption,