zephyr: Clean up docs

Now that we have doc generation, improve the docs to make the generated
docs useful.

Signed-off-by: David Brown <[email protected]>

Author: d3zd3z

zephyr/src/lib.rs

@@ -118,7 +118,8 @@ fn panic(info :&PanicInfo) -> ! {
     }
 }
 
-/// Re-export of zephyr-sys as `zephyr::raw`.
+/// Re-export of zephyr-sys as `zephyr::raw`.  Generally, most users of zephyr will use
+/// `zephyr::raw` instead of directly importing the zephyr-sys crate.
 pub mod raw {
     pub use zephyr_sys::*;
 }

zephyr/src/printk.rs

@@ -35,7 +35,15 @@ macro_rules! printk {
     }};
 }
 
-/// Print to Zephyr's console.
+/// Print to Zephyr's console, with a newline.
+///
+/// This macro uses the same syntax as std's
+/// [`format!`](https://doc.rust-lang.org/std/macro.format.html), but writes to the Zephyr console
+/// instead. See `std::fmt` for more information.
+///
+/// If `CONFIG_PRINTK_SYNC` is enabled, this locks during printing.  However, to avoid allocation,
+/// and due to private accessors in the Zephyr printk implementation, the lock is only over groups
+/// of a small buffer size.  This buffer must be kept fairly small, as it resides on the stack.
 ///
 /// TODO
 #[macro_export]
@@ -112,6 +120,8 @@ impl Write for Context {
     }
 }
 
+/// Implementation of printk, invoked by the printk macro.
+#[doc(hidden)]
 pub fn printk(args: Arguments<'_>) {
     let mut context = Context {
         count: 0,
@@ -121,6 +131,8 @@ pub fn printk(args: Arguments<'_>) {
     context.flush();
 }
 
+/// Implementation of printkln, invoked by the printkln macro.
+#[doc(hidden)]
 pub fn printkln(args: Arguments<'_>) {
     let mut context = Context {
         count: 0,

zephyr/src/sys.rs

@@ -14,5 +14,15 @@ use zephyr_sys::k_timeout_t;
 // These two constants are not able to be captured by bindgen.  It is unlikely that these values
 // would change in the Zephyr headers, but there will be an explicit test to make sure they are
 // correct.
+
+/// Represents a timeout with an infinite delay.
+///
+/// Low-level Zephyr constant.  Calls using this value will wait as long as necessary to perform
+/// the requested operation.
 pub const K_FOREVER: k_timeout_t = k_timeout_t { ticks: -1 };
+
+/// Represents a null timeout delay.
+///
+/// Low-level Zephyr Constant.  Calls using this value will not wait if the operation cannot be
+/// performed immediately.
 pub const K_NO_WAIT: k_timeout_t = k_timeout_t { ticks: 0 };

zephyr/src/time.rs

@@ -34,14 +34,21 @@ use core::fmt::Debug;
 compile_error!("Rust does not (yet) support dynamic frequency timer");
 
 // Given the above not defined, the system time base comes from a kconfig.
-/// The system time base.  The system clock has this many ticks per second.
+/// The system time base.  The system clock has this many ticks per second.  Values such as
+/// timeouts are defined as some number of these ticks.
 pub const SYS_FREQUENCY: u32 = crate::kconfig::CONFIG_SYS_CLOCK_TICKS_PER_SEC as u32;
 
-/// Zephyr can be configured for either 64-bit or 32-bit time values.  Use the appropriate type
-/// internally to match.  This should end up the same size as `k_ticks_t`, but unsigned instead of
-/// signed.
+// Zephyr can be configured for either 64-bit or 32-bit time values.  Use the appropriate type
+// internally to match.  This should end up the same size as `k_ticks_t`, but unsigned instead of
+// signed.
+
+/// Represnts a count of time ticks.  Matches Zephyr's `crate::raw::k_ticks_t`, but as an unsigned
+/// value, to match Fugit's time requirements.
 #[cfg(CONFIG_TIMEOUT_64BIT)]
 pub type Tick = u64;
+
+/// Represnts a count of time ticks.  Matches Zephyr's `crate::raw::k_ticks_t`, but as an unsigned
+/// value, to match Fugit's time requirements.
 #[cfg(not(CONFIG_TIMEOUT_64BIT))]
 pub type Tick = u32;
 
@@ -66,7 +73,11 @@ pub type Instant = fugit::Instant<Tick, 1, SYS_FREQUENCY>;
 // The absolute time offset is only implemented when time is a 64-bit value.  This also means that
 // "Instant" isn't available when time is defined as a 32-bit value.
 
-// Wrapper around the timeout type, so we can implement From/Info.
+/// Wrapper around the timeout type, so we can implement From/Info.
+///
+/// This wrapper allows us to implement `From` and `Info` from the Fugit types into the Zephyr
+/// types.  This allows various methods to accept either value, as well as the `Forever` and
+/// `NoWait` values defined here.
 pub struct Timeout(pub k_timeout_t);
 
 // `From` allows methods to take a time of various types and convert it into a Zephyr timeout.
@@ -89,8 +100,9 @@ impl From<Instant> for Timeout {
     }
 }
 
-/// A sleep that waits forever.  This is its own type, that is `Into<Timeout>` and can be used
-/// anywhere a timeout is needed.
+/// A timeout that waits forever.
+///
+/// This is its own type, that is `Into<Timeout>` and can be used anywhere a timeout is needed.
 pub struct Forever;
 
 impl From<Forever> for Timeout {
@@ -99,8 +111,9 @@ impl From<Forever> for Timeout {
     }
 }
 
-/// A sleep that doesn't ever wait.  This is its own type, that is `Info<Timeout>` and can be used
-/// anywhere a timeout is needed.
+/// A timeout that doesn't ever wait.
+///
+/// This is its own type, that is `Info<Timeout>` and can be used anywhere a timeout is needed.
 pub struct NoWait;
 
 impl From<NoWait> for Timeout {
@@ -109,8 +122,10 @@ impl From<NoWait> for Timeout {
     }
 }
 
-/// Put the current thread to sleep, for the given duration.  Uses `k_sleep` for the actual sleep.
-/// Returns a duration roughly representing the remaining amount of time if the sleep was woken.
+/// Put the current thread to sleep, for the given duration.
+///
+/// Uses `k_sleep` for the actual sleep.  Returns a duration roughly representing the remaining
+/// amount of time if the sleep was woken.
 pub fn sleep<T>(timeout: T) -> Duration
     where T: Into<Timeout>,
 {