From 02b7a833d9855bd1db9665b8e9f311f0db93c156 Mon Sep 17 00:00:00 2001 From: Ulf Lilleengen Date: Fri, 8 Dec 2023 20:42:52 +0100 Subject: [PATCH] docs: document all public apis of embedded-hal-internal * Make some fields and functions non-public where possible. * Enable doc warnings for missing public API docs. --- embassy-hal-internal/src/atomic_ring_buffer.rs | 14 +++++++++++++- embassy-hal-internal/src/drop.rs | 7 ++++++- embassy-hal-internal/src/lib.rs | 1 + embassy-hal-internal/src/macros.rs | 5 +++++ embassy-hal-internal/src/peripheral.rs | 1 + embassy-hal-internal/src/ratio.rs | 1 + 6 files changed, 27 insertions(+), 2 deletions(-) diff --git a/embassy-hal-internal/src/atomic_ring_buffer.rs b/embassy-hal-internal/src/atomic_ring_buffer.rs index ea84925c4..b4f2cec28 100644 --- a/embassy-hal-internal/src/atomic_ring_buffer.rs +++ b/embassy-hal-internal/src/atomic_ring_buffer.rs @@ -1,3 +1,4 @@ +//! Atomic reusable ringbuffer. use core::slice; use core::sync::atomic::{AtomicPtr, AtomicUsize, Ordering}; @@ -14,8 +15,9 @@ use core::sync::atomic::{AtomicPtr, AtomicUsize, Ordering}; /// One concurrent writer and one concurrent reader are supported, even at /// different execution priorities (like main and irq). pub struct RingBuffer { + #[doc(hidden)] pub buf: AtomicPtr, - pub len: AtomicUsize, + len: AtomicUsize, // start and end wrap at len*2, not at len. // This allows distinguishing "full" and "empty". @@ -24,11 +26,16 @@ pub struct RingBuffer { // // This avoids having to consider the ringbuffer "full" at len-1 instead of len. // The usual solution is adding a "full" flag, but that can't be made atomic + #[doc(hidden)] pub start: AtomicUsize, + #[doc(hidden)] pub end: AtomicUsize, } +/// A type which can only read from a ring buffer. pub struct Reader<'a>(&'a RingBuffer); + +/// A type which can only write to a ring buffer. pub struct Writer<'a>(&'a RingBuffer); impl RingBuffer { @@ -89,10 +96,12 @@ impl RingBuffer { Writer(self) } + /// Return length of buffer. pub fn len(&self) -> usize { self.len.load(Ordering::Relaxed) } + /// Check if buffer is full. pub fn is_full(&self) -> bool { let len = self.len.load(Ordering::Relaxed); let start = self.start.load(Ordering::Relaxed); @@ -101,6 +110,7 @@ impl RingBuffer { self.wrap(start + len) == end } + /// Check if buffer is empty. pub fn is_empty(&self) -> bool { let start = self.start.load(Ordering::Relaxed); let end = self.end.load(Ordering::Relaxed); @@ -238,6 +248,7 @@ impl<'a> Writer<'a> { [(unsafe { buf.add(end) }, n0), (buf, n1)] } + /// Mark n bytes as written and advance the write index. pub fn push_done(&mut self, n: usize) { trace!(" ringbuf: push {:?}", n); let end = self.0.end.load(Ordering::Relaxed); @@ -323,6 +334,7 @@ impl<'a> Reader<'a> { (unsafe { buf.add(start) }, n) } + /// Mark n bytes as read and allow advance the read index. pub fn pop_done(&mut self, n: usize) { trace!(" ringbuf: pop {:?}", n); diff --git a/embassy-hal-internal/src/drop.rs b/embassy-hal-internal/src/drop.rs index 7cd16aaec..8383fcc16 100644 --- a/embassy-hal-internal/src/drop.rs +++ b/embassy-hal-internal/src/drop.rs @@ -1,16 +1,20 @@ +//! Types for controlling when drop is invoked. use core::mem; use core::mem::MaybeUninit; -#[must_use = "to delay the drop handler invokation to the end of the scope"] +/// A type to delay the drop handler invocation. +#[must_use = "to delay the drop handler invocation to the end of the scope"] pub struct OnDrop { f: MaybeUninit, } impl OnDrop { + /// Create a new instance. pub fn new(f: F) -> Self { Self { f: MaybeUninit::new(f) } } + /// Prevent drop handler from running. pub fn defuse(self) { mem::forget(self) } @@ -34,6 +38,7 @@ pub struct DropBomb { } impl DropBomb { + /// Create a new instance. pub fn new() -> Self { Self { _private: () } } diff --git a/embassy-hal-internal/src/lib.rs b/embassy-hal-internal/src/lib.rs index f3d59e588..89f20e993 100644 --- a/embassy-hal-internal/src/lib.rs +++ b/embassy-hal-internal/src/lib.rs @@ -1,6 +1,7 @@ #![no_std] #![allow(clippy::new_without_default)] #![doc = include_str!("../README.md")] +#![warn(missing_docs)] // This mod MUST go first, so that the others see its macros. pub(crate) mod fmt; diff --git a/embassy-hal-internal/src/macros.rs b/embassy-hal-internal/src/macros.rs index 97df38954..07cd89487 100644 --- a/embassy-hal-internal/src/macros.rs +++ b/embassy-hal-internal/src/macros.rs @@ -1,3 +1,4 @@ +/// Types for the peripheral singletons. #[macro_export] macro_rules! peripherals_definition { ($($(#[$cfg:meta])? $name:ident),*$(,)?) => { @@ -29,6 +30,7 @@ macro_rules! peripherals_definition { }; } +/// Define the peripherals struct. #[macro_export] macro_rules! peripherals_struct { ($($(#[$cfg:meta])? $name:ident),*$(,)?) => { @@ -87,6 +89,7 @@ macro_rules! peripherals_struct { }; } +/// Defining peripheral type. #[macro_export] macro_rules! peripherals { ($($(#[$cfg:meta])? $name:ident),*$(,)?) => { @@ -105,6 +108,7 @@ macro_rules! peripherals { }; } +/// Convenience converting into reference. #[macro_export] macro_rules! into_ref { ($($name:ident),*) => { @@ -114,6 +118,7 @@ macro_rules! into_ref { } } +/// Implement the peripheral trait. #[macro_export] macro_rules! impl_peripheral { ($type:ident) => { diff --git a/embassy-hal-internal/src/peripheral.rs b/embassy-hal-internal/src/peripheral.rs index 38b4c452e..16d49edfb 100644 --- a/embassy-hal-internal/src/peripheral.rs +++ b/embassy-hal-internal/src/peripheral.rs @@ -20,6 +20,7 @@ pub struct PeripheralRef<'a, T> { } impl<'a, T> PeripheralRef<'a, T> { + /// Create a new reference to a peripheral. #[inline] pub fn new(inner: T) -> Self { Self { diff --git a/embassy-hal-internal/src/ratio.rs b/embassy-hal-internal/src/ratio.rs index 9a8808a33..91dcfd47c 100644 --- a/embassy-hal-internal/src/ratio.rs +++ b/embassy-hal-internal/src/ratio.rs @@ -1,3 +1,4 @@ +//! Types for dealing with rational numbers. use core::ops::{Add, Div, Mul}; use num_traits::{CheckedAdd, CheckedDiv, CheckedMul};