Deny missing docs at the package level, adding exceptions for relevant modules (#1931)

esp-hal/src/aes/mod.rs

@@ -46,8 +46,6 @@
 //! * AES-DMA mode is currently not supported on ESP32 and ESP32S2
 //! * AES-DMA Initialization Vector (IV) is currently not supported
 
-#![deny(missing_docs)]
-
 use crate::{
     peripheral::{Peripheral, PeripheralRef},
     peripherals::AES,

esp-hal/src/analog/mod.rs

@@ -5,8 +5,6 @@
 //! available on the device. For more information about a peripheral driver,
 //! please refer to the relevant module documentation.
 
-#![deny(missing_docs)]
-
 #[cfg(adc)]
 pub mod adc;
 #[cfg(dac)]

esp-hal/src/clock/mod.rs

@@ -70,8 +70,6 @@
 //! # }
 //! ```
 
-#![deny(missing_docs)]
-
 use fugit::HertzU32;
 
 #[cfg(any(esp32, esp32c2))]

esp-hal/src/dma/mod.rs

@@ -50,8 +50,6 @@
 //!
 //! For convenience you can use the [crate::dma_buffers] macro.
 
-#![deny(missing_docs)]
-
 use core::{fmt::Debug, marker::PhantomData, ptr::addr_of_mut, sync::atomic::compiler_fence};
 
 trait Word: crate::private::Sealed {}

esp-hal/src/ecc.rs

@@ -25,6 +25,8 @@
 //!
 //! [ECC]: https://github.com/esp-rs/esp-hal/blob/main/hil-test/tests/ecc.rs
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 use core::marker::PhantomData;
 
 use crate::{

esp-hal/src/etm.rs

@@ -61,6 +61,8 @@
 //! # }
 //! ```
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 use crate::{
     peripheral::{Peripheral, PeripheralRef},
     system::PeripheralClockControl,

esp-hal/src/gpio/mod.rs

@@ -46,8 +46,6 @@
 //! [Commonly Used Setup]: ../index.html#commonly-used-setup
 //! [Inverting TX and RX Pins]: ../uart/index.html#inverting-tx-and-rx-pins
 
-#![warn(missing_docs)]
-
 use core::{cell::Cell, marker::PhantomData};
 
 use critical_section::Mutex;

esp-hal/src/hmac.rs

@@ -34,6 +34,8 @@
 //!
 //! [HMAC]: https://github.com/esp-rs/esp-hal/blob/main/examples/src/bin/hmac.rs
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 use core::convert::Infallible;
 
 use crate::{

esp-hal/src/i2c.rs

@@ -69,6 +69,8 @@
 //! # }
 //! ```
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 use core::marker::PhantomData;
 
 use fugit::HertzU32;

esp-hal/src/i2s.rs

@@ -80,6 +80,8 @@
 //! - Only master mode is supported.
 //! - Only TDM Philips standard is supported.
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 use core::marker::PhantomData;
 
 use enumset::{EnumSet, EnumSetType};

esp-hal/src/interrupt/mod.rs

@@ -73,8 +73,6 @@
 //! }
 //! ```
 
-#![warn(missing_docs)]
-
 use core::ops::BitAnd;
 
 #[cfg(riscv)]

esp-hal/src/lcd_cam/mod.rs

@@ -5,6 +5,8 @@
 //! used simultaneously. For more information on these modules, please refer to
 //! the documentation in their respective modules.
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 pub mod cam;
 pub mod lcd;
 

esp-hal/src/ledc/mod.rs

@@ -60,6 +60,8 @@
 //! - Source clock selection is not supported
 //! - Interrupts are not supported
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 use self::{
     channel::Channel,
     timer::{Timer, TimerSpeed},

esp-hal/src/lib.rs

@@ -142,7 +142,7 @@
 #![allow(asm_sub_register)]
 #![cfg_attr(feature = "async", allow(stable_features, async_fn_in_trait))]
 #![cfg_attr(xtensa, feature(asm_experimental_arch))]
-#![deny(rust_2018_idioms)]
+#![deny(missing_docs, rust_2018_idioms)]
 #![no_std]
 
 // MUST be the first module
@@ -601,6 +601,7 @@ pub struct FlashSafeDma<T, const SIZE: usize> {
 }
 
 impl<T, const SIZE: usize> FlashSafeDma<T, SIZE> {
+    /// Create a new instance wrapping a given buffer
     pub fn new(inner: T) -> Self {
         Self {
             inner,
@@ -608,14 +609,17 @@ impl<T, const SIZE: usize> FlashSafeDma<T, SIZE> {
         }
     }
 
+    /// Return a mutable reference to the inner buffer
     pub fn inner_mut(&mut self) -> &mut T {
         &mut self.inner
     }
 
+    /// Return an immutable reference to the inner buffer
     pub fn inner(&self) -> &T {
         &self.inner
     }
 
+    /// Free the inner buffer
     pub fn free(self) -> T {
         self.inner
     }

esp-hal/src/mcpwm/mod.rs

@@ -83,8 +83,6 @@
 //! # }
 //! ```
 
-#![deny(missing_docs)]
-
 use core::{marker::PhantomData, ops::Deref};
 
 use fugit::HertzU32;

esp-hal/src/otg_fs.rs

@@ -36,6 +36,8 @@
 //! ## Implementation State
 //! - Low-speed (LS) is not supported.
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 pub use esp_synopsys_usb_otg::UsbBus;
 use esp_synopsys_usb_otg::UsbPeripheral;
 

esp-hal/src/parl_io.rs

@@ -23,8 +23,6 @@
 //!
 //! [Parallel IO TX]: https://github.com/esp-rs/esp-hal/blob/main/examples/src/bin/parl_io_tx.rs
 
-#![warn(missing_docs)]
-
 use core::marker::PhantomData;
 
 use enumset::{EnumSet, EnumSetType};

esp-hal/src/pcnt/mod.rs

@@ -20,6 +20,8 @@
 //! [unit]: unit/index.html
 //! [PCNT Encoder]: https://github.com/esp-rs/esp-hal/blob/main/examples/src/bin/pcnt_encoder.rs
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 use self::unit::Unit;
 use crate::{
     interrupt::{self, InterruptHandler},

esp-hal/src/peripheral.rs

@@ -46,6 +46,7 @@ pub struct PeripheralRef<'a, T> {
 }
 
 impl<'a, T> PeripheralRef<'a, T> {
+    /// Create a new exclusive reference to a peripheral
     #[inline]
     pub fn new(inner: T) -> Self {
         Self {

esp-hal/src/reset.rs

@@ -17,6 +17,7 @@
 
 use crate::rtc_cntl::SocResetReason;
 
+/// Source of the wakeup event
 #[derive(Debug, Copy, Clone)]
 pub enum SleepSource {
     /// In case of deep sleep, reset was not caused by exit from deep sleep

esp-hal/src/rmt.rs

@@ -79,8 +79,6 @@
 //! (on ESP32 and ESP32-S2 you cannot specify a base frequency other than 80
 //! MHz)
 
-#![warn(missing_docs)]
-
 use core::marker::PhantomData;
 
 use fugit::HertzU32;

esp-hal/src/rsa/mod.rs

@@ -34,6 +34,8 @@
 //! [nb]: https://docs.rs/nb/1.1.0/nb/
 //! [the repository with corresponding example]: https://github.com/esp-rs/esp-hal/blob/main/hil-test/tests/rsa.rs
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 use core::{marker::PhantomData, ptr::copy_nonoverlapping};
 
 use crate::{

esp-hal/src/rtc_cntl/mod.rs

@@ -69,6 +69,8 @@
 //! }
 //! ```
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 #[cfg(not(any(esp32c6, esp32h2)))]
 use fugit::HertzU32;
 use fugit::MicrosDurationU64;

esp-hal/src/sha.rs

@@ -57,6 +57,8 @@
 //! ## Implementation State
 //! - DMA-SHA Mode is not supported.
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 use core::{convert::Infallible, marker::PhantomData};
 
 use crate::{

esp-hal/src/soc/mod.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)] // TODO: Remove when able
+
 use portable_atomic::{AtomicU8, Ordering};
 
 pub use self::implementation::*;

esp-hal/src/spi/mod.rs

@@ -9,6 +9,8 @@
 //! more information on these modes, please refer to the documentation in their
 //! respective modules.
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 use crate::dma::DmaError;
 
 pub mod master;

esp-hal/src/system.rs

@@ -29,6 +29,8 @@
 //! # }
 //! ```
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 use crate::{
     interrupt::InterruptHandler,
     peripheral::PeripheralRef,

esp-hal/src/time.rs

@@ -10,7 +10,6 @@
 //! let time = time::current_time();
 //! # }
 //! ```
-#![warn(missing_docs)]
 
 /// Provides time since system start in microseconds precision
 ///

esp-hal/src/timer/mod.rs

@@ -38,8 +38,6 @@
 //! # }
 //! ```
 
-#![deny(missing_docs)]
-
 use fugit::{ExtU64, Instant, MicrosDurationU64};
 
 use crate::{

esp-hal/src/touch.rs

@@ -27,8 +27,6 @@
 //! - Touch sensor slope control
 //! - Deep Sleep support (wakeup from Deep Sleep)
 
-#![deny(missing_docs)]
-
 use core::marker::PhantomData;
 
 use crate::{

esp-hal/src/trace.rs

@@ -42,13 +42,16 @@ use crate::{
 /// Errors returned from [Trace::stop_trace]
 #[derive(Debug, Clone, Copy)]
 pub enum Error {
+    /// Attempted to stop a trace which had not been started yet
     NotStarted,
 }
 
 /// Returned by [Trace::stop_trace]
 #[derive(Debug, Clone, Copy)]
 pub struct TraceResult {
+    /// Start index of the valid data
     pub valid_start_index: usize,
+    /// Length of the valid data
     pub valid_length: usize,
 }
 
@@ -200,7 +203,9 @@ where
     }
 }
 
+/// Trace peripheral instance
 pub trait Instance: crate::private::Sealed {
+    /// Get a reference to the peripheral's underlying register block
     fn register_block(&self) -> &RegisterBlock;
 }
 

esp-hal/src/twai/mod.rs

@@ -129,6 +129,8 @@
 //! # }
 //! ```
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 use core::marker::PhantomData;
 
 use self::filter::{Filter, FilterType};

esp-hal/src/uart.rs

@@ -118,6 +118,8 @@
 //! [embedded-hal-async]: https://docs.rs/embedded-hal-async/latest/embedded_hal_async/
 //! [embedded-io-async]: https://docs.rs/embedded-io-async/latest/embedded_io_async/
 
+#![allow(missing_docs)] // TODO: Remove when able
+
 use core::marker::PhantomData;
 
 use self::config::Config;

esp-hal/src/usb_serial_jtag.rs

@@ -338,6 +338,7 @@ where
         self.tx.flush_tx_nb()
     }
 
+    /// Read a single byte but don't block if it isn't ready immediately
     pub fn read_byte(&mut self) -> nb::Result<u8, Error> {
         self.rx.read_byte()
     }