Repository: tock/tock (language: rust)

Issue:
Doc: -Z unstable-options --document-hidden-items causes `Kernel` struct to not be documented.
Currently on https://docs.tockos.org/kernel/, there is no documentation for the `Kernel` struct:

<img width="462" alt="image" src="https://github.com/tock/tock/assets/1467890/9365cdb8-9efc-48d8-879f-7ad511fbb0aa">

That `Kernel` type is not a link.

However, when built locally:

```
cd tock/kernel
cargo doc
open ../target/doc/kernel/index.html
```

It looks as expected:

<img width="594" alt="image" src="https://github.com/tock/tock/assets/1467890/01b6de37-afec-4729-b690-5ea8530dec2c">


I tracked this down to using the `-Z unstable-options --document-hidden-items` flag. If I include that when building kernel docs I get the undocumented `Kernel` struct.


Discussion / hints:
It's hilarious that an option to document more can cause Rustdoc to generate _less_ docs. :upside_down_face: 
The fix might be to change to `cargo doc --document-private-items` which is perhaps what we actually wanted.

Fix patch:
diff --git a/arch/rv32i/src/pmp.rs b/arch/rv32i/src/pmp.rs
index f1e93ca3cf..e914d4838b 100644
--- a/arch/rv32i/src/pmp.rs
+++ b/arch/rv32i/src/pmp.rs
@@ -205,7 +205,7 @@ impl TORRegionSpec {
 /// Helper method to check if a [`PMPUserMPUConfig`] region overlaps with a
 /// region specified by `other_start` and `other_size`.
 ///
-/// Matching the RISC-V spec this checks pmpaddr[i-i] <= y < pmpaddr[i] for TOR
+/// Matching the RISC-V spec this checks `pmpaddr[i-i] <= y < pmpaddr[i]` for TOR
 /// ranges.
 fn region_overlaps(
     region: &(TORUserPMPCFG, *const u8, *const u8),
diff --git a/boards/Makefile.common b/boards/Makefile.common
index ab35928faa..5a4f52f92d 100644
--- a/boards/Makefile.common
+++ b/boards/Makefile.common
@@ -237,7 +237,7 @@ CARGO_FLAGS_TOCK ?= \
   --target-dir=$(TARGET_DIRECTORY) $(CARGO_FLAGS)
 
 # Add default flags to rustdoc.
-RUSTDOC_FLAGS_TOCK ?= -D warnings
+RUSTDOC_FLAGS_TOCK ?= -D warnings --document-private-items
 
 # Add flags if we are compiling on nightly. If we are on stable, disallow
 # features.
@@ -256,7 +256,6 @@ ifneq ($(USE_STABLE_RUST),1)
   CARGO_FLAGS_TOCK += \
     -Z build-std=core,compiler_builtins \
     -Z build-std-features="core/optimize_for_size"
-  RUSTDOC_FLAGS_TOCK += -Z unstable-options --document-hidden-items
 endif
 
 # Set the default flags we need for objdump to get a .lst file.
diff --git a/capsules/core/src/virtualizers/virtual_i2c.rs b/capsules/core/src/virtualizers/virtual_i2c.rs
index f103764d58..5385926e36 100644
--- a/capsules/core/src/virtualizers/virtual_i2c.rs
+++ b/capsules/core/src/virtualizers/virtual_i2c.rs
@@ -178,8 +178,7 @@ impl<'a, I: i2c::I2CMaster<'a>, S: i2c::SMBusMaster<'a>> MuxI2C<'a, I, S> {
     /// requiring a callback with an error condition; if the operation
     /// is executed synchronously, the callback may be reentrant (executed
     /// during the downcall). Please see
-    ///
-    /// https://github.com/tock/tock/issues/1496
+    /// <https://github.com/tock/tock/issues/1496>
     fn do_next_op_async(&self) {
         self.deferred_call.set();
     }
diff --git a/capsules/core/src/virtualizers/virtual_spi.rs b/capsules/core/src/virtualizers/virtual_spi.rs
index 04b957802d..b2955b3aef 100644
--- a/capsules/core/src/virtualizers/virtual_spi.rs
+++ b/capsules/core/src/virtualizers/virtual_spi.rs
@@ -125,8 +125,7 @@ impl<'a, Spi: hil::spi::SpiMaster<'a>> MuxSpiMaster<'a, Spi> {
     /// requiring a callback with an error condition; if the operation
     /// is executed synchronously, the callback may be reentrant (executed
     /// during the downcall). Please see
-    ///
-    /// https://github.com/tock/tock/issues/1496
+    /// <https://github.com/tock/tock/issues/1496>
     fn do_next_op_async(&self) {
         self.deferred_call.set();
     }
diff --git a/capsules/core/src/virtualizers/virtual_uart.rs b/capsules/core/src/virtualizers/virtual_uart.rs
index 1dff12d7ad..4bd38a897a 100644
--- a/capsules/core/src/virtualizers/virtual_uart.rs
+++ b/capsules/core/src/virtualizers/virtual_uart.rs
@@ -307,8 +307,7 @@ impl<'a> MuxUart<'a> {
     /// requiring a callback with an error condition; if the operation
     /// is executed synchronously, the callback may be reentrant (executed
     /// during the downcall). Please see
-    ///
-    /// https://github.com/tock/tock/issues/1496
+    /// <https://github.com/tock/tock/issues/1496>
     fn do_next_op_async(&self) {
         self.deferred_call.set();
     }
diff --git a/capsules/extra/src/bmp280.rs b/capsules/extra/src/bmp280.rs
index 303524fd61..a8a6d76736 100644
--- a/capsules/extra/src/bmp280.rs
+++ b/capsules/extra/src/bmp280.rs
@@ -33,24 +33,24 @@ enum Register {
     DIG_T3 = 0x8c,
     ID = 0xd0,
     RESET = 0xe0,
-    /// measuring: [3]
-    /// im_update: [0]
+    // measuring: [3]
+    // im_update: [0]
     STATUS = 0xf3,
-    /// osrs_t: [7:5]
-    /// osrs_p: [4:2]
-    /// mode: [1:0]
+    // osrs_t: [7:5]
+    // osrs_p: [4:2]
+    // mode: [1:0]
     CTRL_MEAS = 0xf4,
-    /// t_sb: [7:5]
-    /// filter: [4:2]
-    /// spi3w_en: [0]
+    // t_sb: [7:5]
+    // filter: [4:2]
+    // spi3w_en: [0]
     CONFIG = 0xf5,
     PRESS_MSB = 0xf7,
     PRESS_LSB = 0xf8,
-    /// xlsb: [7:4]
+    // xlsb: [7:4]
     PRESS_XLSB = 0xf9,
     TEMP_MSB = 0xfa,
     TEMP_LSB = 0xfb,
-    /// xlsb: [7:4]
+    // xlsb: [7:4]
     TEMP_XLSB = 0xfc,
 }
 
diff --git a/capsules/extra/src/hmac_sha256.rs b/capsules/extra/src/hmac_sha256.rs
index e27b8b5b7c..1b63c8a04e 100644
--- a/capsules/extra/src/hmac_sha256.rs
+++ b/capsules/extra/src/hmac_sha256.rs
@@ -46,7 +46,8 @@ pub struct HmacSha256Software<'a, S: hil::digest::Sha256 + hil::digest::DigestDa
     /// The current operation for the internal state machine in this capsule.
     state: Cell<State>,
     /// The current mode of operation as requested by a call to either
-    /// [`DigestHash::run`] or [`DigestVerify::verify`].
+    /// [`DigestHash::run`](kernel::hil::digest::DigestHash::run) or
+    /// [`DigestVerify::verify`](kernel::hil::digest::DigestVerify::verify).
     mode: Cell<RunMode>,
     /// Location to store incoming temporarily before we are able to pass it to
     /// the hasher.
diff --git a/capsules/extra/src/usb/ctap.rs b/capsules/extra/src/usb/ctap.rs
index 90fb04af6c..b5c39a24aa 100644
--- a/capsules/extra/src/usb/ctap.rs
+++ b/capsules/extra/src/usb/ctap.rs
@@ -46,7 +46,7 @@ const N_ENDPOINTS: usize = 2;
 /// This is a combination of:
 ///     - the CTAP spec, example 8
 ///     - USB HID spec examples
-/// Plus it matches: https://chromium.googlesource.com/chromiumos/platform2/+/master/u2fd/u2fhid.cc
+/// Plus it matches: <https://chromium.googlesource.com/chromiumos/platform2/+/master/u2fd/u2fhid.cc>
 static REPORT_DESCRIPTOR: &[u8] = &[
     0x06, 0xD0, 0xF1, // HID_UsagePage ( FIDO_USAGE_PAGE ),
     0x09, 0x01, // HID_Usage ( FIDO_USAGE_CTAPHID ),
diff --git a/capsules/extra/src/usb/keyboard_hid.rs b/capsules/extra/src/usb/keyboard_hid.rs
index 4349c68bea..5f38e3ce03 100644
--- a/capsules/extra/src/usb/keyboard_hid.rs
+++ b/capsules/extra/src/usb/keyboard_hid.rs
@@ -37,7 +37,7 @@ pub const MAX_CTRL_PACKET_SIZE: u8 = 64;
 const N_ENDPOINTS: usize = 1;
 
 /// The HID report descriptor for keyboard from
-/// https://www.usb.org/sites/default/files/hid1_11.pdf
+/// <https://www.usb.org/sites/default/files/hid1_11.pdf>.
 static REPORT_DESCRIPTOR: &[u8] = &[
     0x05, 0x01, // Usage Page (Generic Desktop),
     0x09, 0x06, // Usage (Keyboard),
diff --git a/chips/earlgrey/src/aes.rs b/chips/earlgrey/src/aes.rs
index 0d37ba66ac..66eba02c94 100644
--- a/chips/earlgrey/src/aes.rs
+++ b/chips/earlgrey/src/aes.rs
@@ -152,7 +152,7 @@ impl<'a> Aes<'a> {
     ///
     /// NOTE: This is needed for Verilator, and is suggested by documentation
     ///       in general.
-    /// Refer: https://docs.opentitan.org/hw/ip/aes/doc/#programmers-guide
+    /// Refer: <https://docs.opentitan.org/hw/ip/aes/doc/#programmers-guide>
     fn wait_on_idle_ready(&self) -> Result<(), ErrorCode> {
         for _i in 0..10000 {
             if self.idle() {
diff --git a/chips/imxrt10xx/src/gpio.rs b/chips/imxrt10xx/src/gpio.rs
index 709f049286..3d44f9b2c3 100644
--- a/chips/imxrt10xx/src/gpio.rs
+++ b/chips/imxrt10xx/src/gpio.rs
@@ -98,8 +98,8 @@ enum_from_primitive! {
 
 /// Creates a GPIO ID
 ///
-/// Low 6 bits are the GPIO offset; the '17' in GPIO2[17]
-/// Next 3 bits are the GPIO port; the '2' in GPIO2[17] (base 0 index, 2 -> 1)
+/// Low 6 bits are the GPIO offset; the '17' in `GPIO2[17]`
+/// Next 3 bits are the GPIO port; the '2' in `GPIO2[17]` (base 0 index, 2 -> 1)
 const fn gpio_id(port: GpioPort, offset: u16) -> u16 {
     ((port as u16) << 6) | offset & 0x3F
 }
diff --git a/chips/litex/src/timer.rs b/chips/litex/src/timer.rs
index 0c39f61dde..4f91cec01a 100644
--- a/chips/litex/src/timer.rs
+++ b/chips/litex/src/timer.rs
@@ -65,7 +65,7 @@ pub struct LiteXTimerRegisters<R: LiteXSoCRegisterConfiguration> {
     ///
     /// This register is only present if the SoC was configured with
     /// `timer_update = True`. Therefore, it's only indirectly
-    /// accessed by the [`LiteXTimerUptime`](LiteXTimerUptime) struct,
+    /// accessed by the [`LiteXTimerUptime`] struct,
     /// which a board will need to construct separately.
     uptime_latch: R::ReadWrite8,
     /// Latched uptime since power-up (in `sys_clk` cycles)
@@ -74,7 +74,7 @@ pub struct LiteXTimerRegisters<R: LiteXSoCRegisterConfiguration> {
     ///
     /// This register is only present if the SoC was configured with
     /// `timer_update = True`. Therefore, it's only indirectly
-    /// accessed by the [`LiteXTimerUptime`](LiteXTimerUptime) struct,
+    /// accessed by the [`LiteXTimerUptime`] struct,
     /// which a board will need to construct separately.
     uptime: R::ReadOnly64,
 }
@@ -184,7 +184,7 @@ impl<R: LiteXSoCRegisterConfiguration, F: Frequency> LiteXTimer<'_, R, F> {
     ///
     /// Clients should use the [`LiteXTimerUptime`] wrapper instead,
     /// which exposes this value as part of their
-    /// [`Time::now`](Time::now) implementation.
+    /// [`Time::now`] implementation.
     unsafe fn uptime(&self) -> Ticks64 {
         WriteRegWrapper::wrap(&self.registers.uptime_latch).write(uptime_latch::latch_value::SET);
         self.registers.uptime.get().into()
diff --git a/chips/nrf52/src/ficr.rs b/chips/nrf52/src/ficr.rs
index 85da0dacfe..3a84d4e1cc 100644
--- a/chips/nrf52/src/ficr.rs
+++ b/chips/nrf52/src/ficr.rs
@@ -367,7 +367,7 @@ impl Ficr {
     /// This changed occurred towards the end of 2021 with chips becoming widely
     /// available/used in 2023.
     ///
-    /// See https://devzone.nordicsemi.com/nordic/nordic-blog/b/blog/posts/working-with-the-nrf52-series-improved-approtect
+    /// See <https://devzone.nordicsemi.com/nordic/nordic-blog/b/blog/posts/working-with-the-nrf52-series-improved-approtect>.
     /// for more information.
     pub(crate) fn has_updated_approtect_logic(&self) -> bool {
         // We assume that an unspecified version means that it is new and this
diff --git a/kernel/src/syscall_driver.rs b/kernel/src/syscall_driver.rs
index 758da28ea1..cbf3ac2405 100644
--- a/kernel/src/syscall_driver.rs
+++ b/kernel/src/syscall_driver.rs
@@ -87,13 +87,13 @@ use crate::syscall::SyscallReturn;
 /// in TRD104.
 ///
 /// This is just a wrapper around
-/// [`SyscallReturn`](SyscallReturn) since a
+/// [`SyscallReturn`] since a
 /// `command` driver method may only return primitive integer types as
 /// payload.
 ///
 /// It is important for this wrapper to only be constructable over
 /// variants of
-/// [`SyscallReturn`](SyscallReturn) that are
+/// [`SyscallReturn`] that are
 /// deemed safe for a capsule to construct and return to an
 /// application (e.g. not
 /// [`SubscribeSuccess`](crate::syscall::SyscallReturn::SubscribeSuccess)).


Test patch: