doc: Various fixes from cargo doc warnings

Merges: #125

src/adc.rs

@@ -20,7 +20,7 @@ impl ADCLine {
 
     /// Initialize an ADC line identified by the line number it is assigned on the board
     ///
-    /// Safety: See [init]
+    /// Safety: See [.init()]
     pub unsafe fn from_number(line: u32) -> Result<Self, i32> {
         let line = riot_sys::macro_ADC_LINE(line);
         Self::init(line)

src/async_helpers.rs

@@ -1,5 +1,7 @@
 //! Tools used internally to create futures more easily
 
+use core::future::Future;
+
 /// A trait similar to Future that is practical to implement for the typical RIOT situations where
 /// a waker needs to be converted into a function and argument pointer.
 ///
@@ -12,7 +14,7 @@
 /// While this can legally be implemented without unsafe, practical use will require unsafe, and
 /// that requires sticking to the rules:
 ///
-/// * Whenever [poll()] is called, do whatever the future needs to do after having been awoken. If
+/// * Whenever [.poll()] is called, do whatever the future needs to do after having been awoken. If
 ///   this returns [core::task::Poll::Pending] (and the future wants to be polled ever again), it
 ///   must then pass on the `arg` to some RIOT callback setter together with a static function of a
 ///   suitable signature. Conventionally, that function is called `Self::callback()`.
@@ -32,7 +34,7 @@ pub(crate) trait RiotStyleFuture {
     fn poll(&mut self, arg: *mut riot_sys::libc::c_void) -> core::task::Poll<Self::Output>;
 }
 
-/// Wrapper that makes a [core::future::Future] out of a [RiotStyleFuture] (see there for usage)
+/// Wrapper that makes a [Future] out of a [RiotStyleFuture] (see there for usage)
 // FIXME: I'm not sure the presence and absence of #[pin] is right about these ones, but anyway,
 // given they're not pub, and this module is what captures the unsafety guarantees (assisted by the
 // requirements on RiotStyleFuture), this should be no worse than manually safe-declaring any
@@ -62,7 +64,7 @@ impl<A: RiotStyleFuture> RiotStylePollStruct<A> {
         f.waker.take().map(|w| w.wake());
     }
 }
-impl<A: RiotStyleFuture> core::future::Future for RiotStylePollStruct<A> {
+impl<A: RiotStyleFuture> Future for RiotStylePollStruct<A> {
     type Output = A::Output;
     fn poll(
         mut self: core::pin::Pin<&mut Self>,

src/bluetil.rs

@@ -52,7 +52,7 @@ impl<const L: usize> Ad<heapless::Vec<u8, L>> {
     /// Construct a bluetil_ad_t that represent the current vec state
     ///
     /// This is not unsafe in itself, but usually used with functions that are, and when they
-    /// write into the buffer, it needs the unsafe [Vec::set_len] to propagate that write.
+    /// write into the buffer, it needs the unsafe [heapless::Vec::set_len] to propagate that write.
     fn build(&self) -> bluetil_ad_t {
         bluetil_ad_t {
             buf: self.0.as_ptr() as _,

src/coap_handler/mod.rs

@@ -1,4 +1,4 @@
-//! This module provides a wrappers around a coap_handler::Handler in different versions, all of
-//! which can be registered at a RIOT GcoapHandler.
+//! This module provides a wrappers around a [coap_handler::Handler](coap_handler_0_2::Handler) in
+//! different versions, all of which can be registered at a RIOT GcoapHandler.
 
 pub mod v0_2;

src/coap_handler/v0_2.rs

@@ -12,8 +12,8 @@ use coap_message_0_3::{
 use crate::coap_message::ResponseMessage;
 use crate::gcoap::PacketBuffer;
 
-/// Adapter to get a [crate::gcoap::Handler] from a more generic [coap_handler::Handler], typically
-/// to register it through a [crate::gcoap::SingleHandlerListener].
+/// Adapter to get a [crate::gcoap::Handler] from a more generic [coap_handler_0_2::Handler],
+/// typically to register it through a [crate::gcoap::SingleHandlerListener].
 pub struct GcoapHandler<H>(pub H)
 where
     H: Handler;

src/coap_message/mod.rs

@@ -1,5 +1,7 @@
-//! This module implements [coap_message::ReadableMessage] for, and a wrapper that provides
-//! [coap_message::WritableMessage] around RIOT's coap_pkt_t.
+//! This module implements [coap_message::ReadableMessage](coap_message_0_3::ReadableMessage) for,
+//! and a wrapper that provides
+//! [coap_message::MutableWritableMessage](coap_message_0_3::MutableWritableMessage)
+//! around, RIOT's coap_pkt_t.
 
 mod impl_0_3;
 

src/gcoap.rs

@@ -152,7 +152,8 @@ where
     ///
     /// Note that the taken Handler is a Gcoap [Handler] (which is there really only in case anyone
     /// wants extremely fine-grained control of what gcoap does); if you have a
-    /// [coap_handler::Handler], you can wrap it in [crate::coap_handler::GcoapHandler] to for adaptation.
+    /// [coap_handler_0_2::Handler], you can wrap it in [crate::coap_handler::v0_2::GcoapHandler]
+    /// to for adaptation.
     pub fn new_catch_all(handler: &'a mut H) -> Self {
         Self::new(
             c"/",

src/gnrc/nib.rs

@@ -6,7 +6,7 @@ pub struct NcEntry(riot_sys::gnrc_ipv6_nib_nc_t);
 /// Neighbor Unreachability Detection state
 ///
 /// See
-/// https://doc.riot-os.org/group__net__gnrc__ipv6__nib__nc.html
+/// [the nib_nc documentation](https://doc.riot-os.org/group__net__gnrc__ipv6__nib__nc.html)
 /// for more detailed semantics
 // FIXME can we pull doc from riot_sys?
 #[derive(Debug)]
@@ -54,7 +54,7 @@ impl NudState {
 /// 6LoWPAN address registration (6Lo-AR) state
 ///
 /// See
-/// https://doc.riot-os.org/group__net__gnrc__ipv6__nib__nc.html
+/// [the nib_nc documentation](https://doc.riot-os.org/group__net__gnrc__ipv6__nib__nc.html)
 /// for more detailed semantics
 // FIXME can we pull doc from riot_sys?
 #[derive(Debug)]

src/gpio/mod.rs

@@ -1,7 +1,7 @@
 //! Access to [RIOT's GPIO pins](http://doc.riot-os.org/group__drivers__periph__gpio.html)
 //!
 //! The various configured GPIO types ([InputGPIO], [OutputGPIO], [InOutGPIO]) can be used through
-//! the [embedded_hal::digital::v2] traits. As recommended for infallible types, they also
+//! the [embedded_hal::digital] traits. As recommended for infallible types, they also
 //! provide identically named direct methods, which (for input pins) also work on shared reference.
 
 mod impl_1;
@@ -96,7 +96,7 @@ impl GPIO {
     /// # }
     /// ```
     ///
-    /// See [from_c] for safety constraints.
+    /// See [.from_c()] for safety constraints.
     pub fn from_port_and_pin(port: u32, pin: u32) -> Option<Self> {
         Self::from_c(unsafe { riot_sys::macro_GPIO_PIN(port, pin) })
     }
@@ -162,7 +162,7 @@ impl OutputGPIO {
 
     /// Toggles the pin between high and low.
     ///
-    /// Unlike [`set_high()`] and [`set_low()`], this is not just an alias of the [embedded-hal
+    /// Unlike [`.set_high()`] and [`.set_low()`], this is not just an alias of the [embedded-hal
     /// trait method of the same
     /// name](https://docs.rs/embedded-hal/latest/embedded_hal/digital/trait.StatefulOutputPin.html#method.toggle):
     /// RIOT GPIO pins do not implement [`embedded_hal::digital::StatefulOutputPin`] because they

src/helpers.rs

@@ -105,7 +105,7 @@ mod slice_to_cstr {
 
     /// Error from [SliceToCStr::to_cstr].
     ///
-    /// This will become [core::ffi:FromBytesUntilNulError] once that's stable, and may be changed
+    /// This will become [core::ffi::c_str::FromBytesUntilNulError] once that's stable, and may be changed
     /// without a breaking release even though it's technically a breaking change. (At this point, that
     /// type will be `pub use`d here and deprecated).
     #[derive(Debug)]

src/i2c/mod.rs

@@ -8,7 +8,7 @@ use riot_sys::i2c_t;
 ///
 /// [I2C implementation]: http://doc.riot-os.org/group__drivers__periph__i2c.html
 ///
-/// Actual transactions on this are performed through the [mbedded_hal_0_2::blocking::i2c] traits
+/// Actual transactions on this are performed through the [embedded_hal_0_2::blocking::i2c] traits
 /// implemented by this.
 #[derive(Debug)]
 pub struct I2CDevice {

src/interrupt.rs

@@ -5,7 +5,7 @@
 //! * Utility functions can disable interrupts (creating critical sections), check whether
 //!   interrupts are enabled or to determine whether code is executed in a thread or an ISR.
 //!
-//! * Some functions (eg. [`ZTimer::set_ticks_during`](crate::ztimer::Clock::set_during))
+//! * Some functions (eg. [set_during](crate::thread::ValueInThread<crate::ztimer::Clock>::set_during))
 //!   take callbacks that will be called in an interrupt context.
 //!
 //!   These are typechecked to be Send, as they are moved from the thread to the interrupt context.

src/saul/registration.rs

@@ -79,17 +79,13 @@ where
     _phantom: core::marker::PhantomData<(DEV, DRIV)>,
 }
 
-/// This flipped from *mut phydat_t to *const in https://github.com/RIOT-OS/RIOT/pull/18043
-pub(crate) type WritePhydatPointer =
-    <riot_sys::saul_write_t as crate::helpers::ReturnTypeExtractor>::Arg2Type;
-
 // While the old supported RIOT version has a `saul_notsup` and the new has
 // `saul_{read,write}_notsup`, it's easier to just implement our own. After the 2022.07 release
 // they can go away again, and users go with riot_sys::saul_[...]_notsup
 extern "C" fn saul_read_notsup(_dev: *const libc::c_void, _dat: *mut riot_sys::phydat_t) -> i32 {
     -(riot_sys::ENOTSUP as i32)
 }
-extern "C" fn saul_write_notsup(_dev: *const libc::c_void, _dat: WritePhydatPointer) -> i32 {
+extern "C" fn saul_write_notsup(_dev: *const libc::c_void, _dat: *const riot_sys::phydat_t) -> i32 {
     -(riot_sys::ENOTSUP as i32)
 }
 
@@ -131,7 +127,10 @@ where
         }
     }
 
-    unsafe extern "C" fn write_raw(dev: *const libc::c_void, data: WritePhydatPointer) -> i32 {
+    unsafe extern "C" fn write_raw(
+        dev: *const libc::c_void,
+        data: *const riot_sys::phydat_t,
+    ) -> i32 {
         let device = &*(dev as *const DEV);
         let device = device.into();
         let data = *data;

src/thread/mod.rs

@@ -3,7 +3,7 @@
 //! ## Tokens
 //!
 //! Some thread creation mechanisms (currently only
-//! [`riot_main_with_tokens!`](crate::riot_main_with_tokens!) and not those in here) are "with
+//! [`riot_main!`](crate::riot_main!) and not those in here) are "with
 //! tokens". With these, the zero-sized type [StartToken] is used to pass along the information
 //! that the execution is currently happening in a thread, and more importantly that some
 //! operations doable only once per thread (eg. setting up a message queue) have not yet happed.

src/thread/tokenparts.rs

@@ -41,9 +41,8 @@ pub struct TokenParts<const MSG_SEMANTICS: bool, const MSG_QUEUE: bool, const FL
 impl TokenParts<true, true, true> {
     /// Claim that the current thread has not done anything yet that is covered by this type
     ///
-    /// Do not call yourself; this needs to be public because
-    /// [`riot_main_with_tokens!`](crate::riot_main_with_tokens!) is a macro and thus technically
-    /// called from the main crate.
+    /// Do not call yourself; this needs to be public because [`riot_main!`](crate::riot_main!) is
+    /// a macro and thus technically called from the main crate.
     pub unsafe fn new() -> Self {
         TokenParts {
             _not_send: PhantomData,
@@ -243,7 +242,7 @@ impl InIsr {
     }
 }
 
-/// A value combined with an [InThread](crate::thread::InThread) marker
+/// A value combined with an [`InThread`] marker
 ///
 /// This does barely implement anything on its own, but the module implementing `T` might provide
 /// extra methods.

src/ztimer/mod.rs

@@ -84,7 +84,7 @@ impl<const HZ: u32> ValueInThread<Clock<HZ>> {
     }
 
     /// Pause the current thread for the given duration, possibly exceeding values expressible in
-    /// [Ticks<HZ>].
+    /// [`Ticks<HZ>`].
     ///
     /// The duration is converted into ticks (rounding up), and overflows are caught by sleeping
     /// multiple times.
@@ -144,7 +144,7 @@ impl<const HZ: u32> ValueInThread<Clock<HZ>> {
 }
 
 impl<const HZ: u32> Clock<HZ> {
-    /// Similar to [`sleep_ticks()`], but this does not block but creates a future to be
+    /// Similar to [`.sleep()`], but this does not block but creates a future to be
     /// `.await`ed.
     ///
     /// Note that time starts running only when this is polled, for otherwise there's no pinned
@@ -340,7 +340,7 @@ impl Clock<1> {
     ///
     /// This function verifies (at a small runtime cost) that the caller is in a thread context.
     /// This can be avoided by calling `in_thread.promote(Clock::sec_unbound())` on an existing
-    /// [riot_wrappers::thread::InThread] token.
+    /// [crate::thread::InThread] token.
     #[cfg(riot_module_ztimer_sec)]
     #[doc(alias = "ZTIMER_SEC")]
     pub fn sec() -> ValueInThread<Self> {
@@ -364,7 +364,7 @@ impl Clock<1000> {
     ///
     /// This function verifies (at a small runtime cost) that the caller is in a thread context.
     /// This can be avoided by calling `in_thread.promote(Clock::msec_unbound())` on an existing
-    /// [riot_wrappers::thread::InThread] token.
+    /// [crate::thread::InThread] token.
     #[cfg(riot_module_ztimer_msec)]
     #[doc(alias = "ZTIMER_MSEC")]
     pub fn msec() -> ValueInThread<Self> {
@@ -388,7 +388,7 @@ impl Clock<1000000> {
     ///
     /// This function verifies (at a small runtime cost) that the caller is in a thread context.
     /// This can be avoided by calling `in_thread.promote(Clock::usec_unbound())` on an existing
-    /// [riot_wrappers::thread::InThread] token.
+    /// [crate::thread::InThread] token.
     #[cfg(riot_module_ztimer_usec)]
     #[doc(alias = "ZTIMER_USEC")]
     pub fn usec() -> ValueInThread<Self> {