Ensure board API is documented (#431)

crates/board/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.6.1-git
+
+### Patch
+
+- Document all public API
+
 ## 0.6.0
 
 ### Major

crates/board/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "wasefire-board-api"
-version = "0.6.0"
+version = "0.6.1-git"
 authors = ["Julien Cretin <cretin@google.com>"]
 license = "Apache-2.0"
 publish = true
@@ -151,3 +151,6 @@ internal-software-crypto-ecc = [
   "elliptic-curve?/sec1",
 ]
 internal-software-crypto-hmac = ["dep:hmac"]
+
+[lints.rust]
+missing-docs = "warn"

crates/board/src/crypto.rs

@@ -35,32 +35,46 @@ pub mod ecc;
 
 /// Cryptography interface.
 pub trait Api: Send {
+    /// AES-128-CCM interface.
     #[cfg(feature = "api-crypto-aes128-ccm")]
     type Aes128Ccm: aead::Api<typenum::U16, typenum::U13, Tag = typenum::U4>;
+
+    /// AES-256-GCM interface.
     #[cfg(feature = "api-crypto-aes256-gcm")]
     type Aes256Gcm: aead::Api<typenum::U32, typenum::U12>;
 
+    /// HMAC-SHA-256 interface.
     #[cfg(feature = "api-crypto-hmac-sha256")]
     type HmacSha256: Hmac<KeySize = typenum::U64, OutputSize = typenum::U32>;
+
+    /// HMAC-SHA-384 interface.
     #[cfg(feature = "api-crypto-hmac-sha384")]
     type HmacSha384: Hmac<KeySize = typenum::U128, OutputSize = typenum::U48>;
 
+    /// P-256 interface.
     #[cfg(feature = "api-crypto-p256")]
     type P256: ecc::Api<typenum::U32>;
+
+    /// P-384 interface.
     #[cfg(feature = "api-crypto-p384")]
     type P384: ecc::Api<typenum::U48>;
 
+    /// SHA-256 interface.
     #[cfg(feature = "api-crypto-sha256")]
     type Sha256: Hash<BlockSize = typenum::U64, OutputSize = typenum::U32>;
+
+    /// SHA-384 interface.
     #[cfg(feature = "api-crypto-sha384")]
     type Sha384: Hash<BlockSize = typenum::U128, OutputSize = typenum::U48>;
 }
 
+/// Hash interface.
 #[cfg(feature = "internal-api-crypto-hash")]
 pub trait Hash:
     Support<bool> + Send + Default + BlockSizeUser + Update + FixedOutputReset + HashMarker
 {
 }
+/// HMAC interface.
 #[cfg(feature = "internal-api-crypto-hmac")]
 pub trait Hmac: Support<bool> + Send + KeyInit + Update + FixedOutput + MacMarker {}
 
@@ -73,37 +87,67 @@ impl<
 #[cfg(feature = "internal-api-crypto-hmac")]
 impl<T: Support<bool> + Send + KeyInit + Update + FixedOutput + MacMarker> Hmac for T {}
 
+/// AES-128-CCM interface.
 #[cfg(feature = "api-crypto-aes128-ccm")]
 pub type Aes128Ccm<B> = <super::Crypto<B> as Api>::Aes128Ccm;
+
+/// AES-256-GCM interface.
 #[cfg(feature = "api-crypto-aes256-gcm")]
 pub type Aes256Gcm<B> = <super::Crypto<B> as Api>::Aes256Gcm;
+
+/// HMAC-SHA-256 interface.
 #[cfg(feature = "api-crypto-hmac-sha256")]
 pub type HmacSha256<B> = <super::Crypto<B> as Api>::HmacSha256;
+
+/// HMAC-SHA-384 interface.
 #[cfg(feature = "api-crypto-hmac-sha384")]
 pub type HmacSha384<B> = <super::Crypto<B> as Api>::HmacSha384;
+
+/// P-256 interface.
 #[cfg(feature = "api-crypto-p256")]
 pub type P256<B> = <super::Crypto<B> as Api>::P256;
+
+/// P-384 interface.
 #[cfg(feature = "api-crypto-p384")]
 pub type P384<B> = <super::Crypto<B> as Api>::P384;
+
+/// SHA-256 interface.
 #[cfg(feature = "api-crypto-sha256")]
 pub type Sha256<B> = <super::Crypto<B> as Api>::Sha256;
+
+/// SHA-384 interface.
 #[cfg(feature = "api-crypto-sha384")]
 pub type Sha384<B> = <super::Crypto<B> as Api>::Sha384;
 
+/// AES-128-CCM interface.
 #[cfg(feature = "software-crypto-aes128-ccm")]
 pub type SoftwareAes128Ccm = ccm::Ccm<aes::Aes128, typenum::U4, typenum::U13>;
+
+/// AES-256-GCM interface.
 #[cfg(feature = "software-crypto-aes256-gcm")]
 pub type SoftwareAes256Gcm = aes_gcm::Aes256Gcm;
+
+/// HMAC-SHA-256 interface.
 #[cfg(feature = "software-crypto-hmac-sha256")]
 pub type SoftwareHmacSha256<T> = hmac::SimpleHmac<<T as Api>::Sha256>;
+
+/// HMAC-SHA-384 interface.
 #[cfg(feature = "software-crypto-hmac-sha384")]
 pub type SoftwareHmacSha384<T> = hmac::SimpleHmac<<T as Api>::Sha384>;
+
+/// P-256 interface.
 #[cfg(feature = "software-crypto-p256")]
 pub type SoftwareP256<T> = ecc::Software<p256::NistP256, <T as Api>::Sha256>;
+
+/// P-384 interface.
 #[cfg(feature = "software-crypto-p384")]
 pub type SoftwareP384<T> = ecc::Software<p384::NistP384, <T as Api>::Sha384>;
+
+/// SHA-256 interface.
 #[cfg(feature = "software-crypto-sha256")]
 pub type SoftwareSha256 = sha2::Sha256;
+
+/// SHA-384 interface.
 #[cfg(feature = "software-crypto-sha384")]
 pub type SoftwareSha384 = sha2::Sha384;
 

crates/board/src/crypto/aead.rs

@@ -18,9 +18,13 @@ use generic_array::{ArrayLength, GenericArray};
 
 use crate::{Error, Support};
 
+/// Describes how AEAD is supported.
 #[derive(Copy, Clone)]
 pub struct AeadSupport {
+    /// The implementation doesn't copy when the input and output are in distinct buffers.
     pub no_copy: bool,
+
+    /// The implementation doesn't copy when the input and output are in the same buffer.
     pub in_place_no_copy: bool,
 }
 
@@ -58,6 +62,7 @@ where
     ) -> Result<(), Error>;
 }
 
+/// Sequence of N bytes.
 pub type Array<N> = GenericArray<u8, N>;
 
 #[cfg(feature = "internal-software-crypto-aead")]

crates/board/src/crypto/ecc.rs

@@ -67,6 +67,7 @@ mod software {
     use super::*;
     use crate::Support;
 
+    /// Generic elliptic-curve software implementation.
     pub struct Software<C, D> {
         curve: PhantomData<C>,
         digest: PhantomData<D>,

crates/board/src/gpio.rs

@@ -14,32 +14,58 @@
 
 //! Low-level GPIO interface.
 
+// TODO(https://github.com/Lokathor/bytemuck/issues/235): Remove once fixed.
+#![allow(missing_docs)]
+
 use crate::{Error, Id, Support};
 
+/// Input GPIO configuration.
 #[derive(Debug, Copy, Clone, bytemuck::CheckedBitPattern)]
 #[repr(u8)]
 pub enum InputConfig {
+    /// Input is disabled.
     Disabled = 0,
+
+    /// Input is floating.
     Floating = 1,
+
+    /// Input has a pull-down resistor.
     PullDown = 2,
+
+    /// Input has a pull-up resistor.
     PullUp = 3,
 }
 
+/// Output GPIO configuration.
 #[derive(Debug, Copy, Clone, bytemuck::CheckedBitPattern)]
 #[repr(u8)]
 pub enum OutputConfig {
+    /// Output is disabled.
     Disabled = 0,
+
+    /// Output can only drive low.
     OpenDrain = 1,
+
+    /// Output can only drive high.
     OpenSource = 2,
+
+    /// Output can drive both low and high.
     PushPull = 3,
 }
 
+/// GPIO configuration.
 #[derive(Debug, Copy, Clone, bytemuck::CheckedBitPattern)]
 #[repr(C)]
 pub struct Config {
+    /// Input configuration.
     pub input: InputConfig,
+
+    /// Output configuration.
     pub output: OutputConfig,
+
+    /// Initial output value.
     pub initial: bool,
+
     reserved: u8,
 }
 

crates/board/src/lib.rs

@@ -77,27 +77,50 @@ pub trait Api: Send + 'static {
         None
     }
 
+    /// Button interface.
     #[cfg(feature = "api-button")]
     type Button: button::Api;
+
+    /// Cryptography interface.
     #[cfg(feature = "internal-api-crypto")]
     type Crypto: crypto::Api;
+
+    /// Debugging and testing interface.
     type Debug: debug::Api;
+
+    /// Low-level GPIO interface.
     #[cfg(feature = "api-gpio")]
     type Gpio: gpio::Api;
+
+    /// LED interface.
     #[cfg(feature = "api-led")]
     type Led: led::Api;
+
+    /// Platform interface.
     #[cfg(feature = "internal-api-platform")]
     type Platform: platform::Api;
+
+    /// Radio interface.
     #[cfg(feature = "internal-api-radio")]
     type Radio: radio::Api;
+
+    /// Random number generator interface.
     #[cfg(feature = "api-rng")]
     type Rng: rng::Api;
+
+    /// Persistent storage interface.
     #[cfg(feature = "api-storage")]
     type Storage: Singleton + wasefire_store::Storage + Send;
+
+    /// Timer interface.
     #[cfg(feature = "api-timer")]
     type Timer: timer::Api;
+
+    /// UART interface.
     #[cfg(feature = "api-uart")]
     type Uart: uart::Api;
+
+    /// USB interface.
     #[cfg(feature = "internal-api-usb")]
     type Usb: usb::Api;
 }
@@ -107,6 +130,7 @@ pub trait Api: Send + 'static {
 /// The `Value` type parameter is usually `bool`. It may also be `usize` for APIs that have multiple
 /// similar things like buttons, leds, and timers.
 pub trait Support<Value> {
+    /// Whether and how the API is supported.
     const SUPPORT: Value;
 }
 
@@ -177,6 +201,7 @@ impl<B: Api + ?Sized> PartialOrd for Impossible<B> {
 }
 
 impl<B: Api + ?Sized> Impossible<B> {
+    /// Provides a static proof of dead code.
     pub fn unreachable(&self) -> ! {
         match self.0 {}
     }
@@ -185,27 +210,50 @@ impl<B: Api + ?Sized> Impossible<B> {
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq, PartialOrd, Ord)]
 enum Void {}
 
+/// Button interface.
 #[cfg(feature = "api-button")]
 pub type Button<B> = <B as Api>::Button;
+
+/// Cryptography interface.
 #[cfg(feature = "internal-api-crypto")]
 pub type Crypto<B> = <B as Api>::Crypto;
+
+/// Debugging and testing interface.
 pub type Debug<B> = <B as Api>::Debug;
+
+/// Low-level GPIO interface.
 #[cfg(feature = "api-gpio")]
 pub type Gpio<B> = <B as Api>::Gpio;
+
+/// LED interface.
 #[cfg(feature = "api-led")]
 pub type Led<B> = <B as Api>::Led;
+
+/// Platform interface.
 #[cfg(feature = "internal-api-platform")]
 pub type Platform<B> = <B as Api>::Platform;
+
+/// Radio interface.
 #[cfg(feature = "internal-api-radio")]
 pub type Radio<B> = <B as Api>::Radio;
+
+/// Random number generator interface.
 #[cfg(feature = "api-rng")]
 pub type Rng<B> = <B as Api>::Rng;
+
+/// Persistent storage interface.
 #[cfg(feature = "api-storage")]
 pub type Storage<B> = <B as Api>::Storage;
+
+/// Timer interface.
 #[cfg(feature = "api-timer")]
 pub type Timer<B> = <B as Api>::Timer;
+
+/// UART interface.
 #[cfg(feature = "api-uart")]
 pub type Uart<B> = <B as Api>::Uart;
+
+/// USB interface.
 #[cfg(feature = "internal-api-usb")]
 pub type Usb<B> = <B as Api>::Usb;
 
@@ -234,6 +282,7 @@ impl<T: Support<usize> + ?Sized> PartialOrd for Id<T> {
 }
 
 impl<T: Support<usize>> Id<T> {
+    /// Creates a safe identifier for an API with countable support.
     pub fn new(value: usize) -> Option<Self> {
         (value < T::SUPPORT).then_some(Self { value, count: PhantomData })
     }

crates/board/src/platform.rs

@@ -22,6 +22,7 @@ pub mod update;
 
 /// Platform interface.
 pub trait Api: Send {
+    /// Platform update interface.
     #[cfg(feature = "api-platform-update")]
     type Update: update::Api;
 
@@ -40,6 +41,7 @@ pub trait Api: Send {
     fn reboot() -> Result<!, Error>;
 }
 
+/// Platform update interface.
 #[cfg(feature = "api-platform-update")]
 pub type Update<B> = <super::Platform<B> as Api>::Update;
 

crates/board/src/radio.rs

@@ -33,9 +33,11 @@ impl<B: crate::Api> From<Event> for crate::Event<B> {
 
 /// Radio interface.
 pub trait Api: Send {
+    /// Bluetooth Low Energy (BLE) interface.
     #[cfg(feature = "api-radio-ble")]
     type Ble: ble::Api;
 }
 
+/// Bluetooth Low Energy (BLE) interface.
 #[cfg(feature = "api-radio-ble")]
 pub type Ble<B> = <super::Radio<B> as Api>::Ble;