Rename Once to OneShot; add docs

Author: Brandon Matthews

src/adc.rs

@@ -2,39 +2,62 @@
 
 use nb;
 
-/// This trait denotes an object, e.g. a GPIO pin, that is configured for use as an ADC channel.
-/// Objects of this type are passed to ADC-mode-specific methods.
+/// A marker trait to identify MCU pins that can be used as inputs to an ADC channel.
+///
+/// This marker trait denotes an object, i.e. a GPIO pin, that is ready for use as an input to the
+/// ADC. As ADCs channels can be supplied by multiple pins, this trait defines the relationship
+/// between the physical interface and the ADC sampling buffer.
 pub trait AdcChannel {
     /// Channel ID type
     ///
-    /// e.g. u8 for ADC channels 1-n, or a (partid, pinid) tuple for something more complex.
+    /// A type used to identify this ADC channel. For example, if the ADC has eight channels, this
+    /// might be a `u8`. If the ADC has multiple banks of channels, it could be a tuple, like
+    /// `(u8: bank_id, u8: channel_id)`.
     type ID;
 
-    /// ID of the channel associated with this pin
+    /// The specific ID that identifies this channel, for example `0` for the first ADC channel.
     const CHANNEL: Self::ID;
 }
 
 /// ADCs that sample on single channels per request, and do so at the time of the request.
-pub trait Once<Word, Pin: AdcChannel> {
+///
+/// This trait is the interface to an ADC that is configured to read a specific channel at the time
+/// of the request (in contrast to continuous asynchronous sampling).
+pub trait OneShot<Word, Pin: AdcChannel> {
     /// Error type returned by ADC methods
     type Error;
 
-    /// Take an analog reading from the specified pin
+    /// Request that the ADC begin a conversion on the specified pin
+    ///
+    /// This method takes a `Pin` reference, as it is expected that the ADC will be able to sample
+    /// whatever channel underlies the pin.
     fn read_channel(&mut self, pin: &mut Pin) -> nb::Result<Word, Self::Error>;
 }
 
-/// ADCs that sample continuously without requiring requests
+/// ADCs that sample continuously or asynchrounously
+///
+/// This trait is the interface to an ADC that is configured to sample one or more `Pin`s on a
+/// regular and recurring basis, without requiring that the channel be sampled at the time of the
+/// request.
 pub trait Continuous<Word, Pin: AdcChannel> {
     /// Error type returned by ADC methods
     type Error;
 
-    /// Take ownership of an ADC channel/pin
-    fn add_channel(&mut self, pin: Pin) -> nb::Result<(), Self::Error>;
+    /// Add a `Pin` (and its channel) to those that are to be sampled
+    ///
+    /// This method moves the Pin, and configures the ADC to include this pin's channel in those
+    /// that it will sample asynchronously.
+    fn add_pin(&mut self, pin: Pin) -> nb::Result<(), Self::Error>;
 
-    /// Release the ADC channel/pin
-    fn release_channel(&mut self, id: Pin::ID) -> nb::Result<Pin, Self::Error>;
+    /// Remove the specified channel from those sampled, and release its pin.
+    ///
+    /// This method removes the channel identified by `id` from the channels that the ADC
+    /// asynchronously samples. It then releases the `Pin` and returns it to the user.
+    fn release_pin(&mut self, id: Pin::ID) -> nb::Result<Pin, Self::Error>;
 
     /// Start a continuous conversion cycle
+    ///
+    /// This starts the ADC sampling its configured channels continuously.
     fn start(&mut self) -> nb::Result<(), Self::Error>;
 
     /// Stop conversions.
@@ -43,8 +66,14 @@ pub trait Continuous<Word, Pin: AdcChannel> {
     fn stop(&mut self) -> nb::Result<(), Self::Error>;
 
     /// Read the specified channel
+    ///
+    /// Read the most recently sampled value for the specified channel.
     fn read(&mut self, chan: Pin::ID) -> nb::Result<Word, Self::Error>;
 }
 
-/// Run conversions in a burst that does not automatically loop or repeat
+/// ADCs that sample a set of channels in a "burst" that does not loop or repeat
+///
+/// This trait is the interface to an ADC that is configured to read from multiple channels
+/// beginning at the time of the request. Unlike `Continuous`, the channels are only read once, and
+/// then the conversions stop.
 pub trait Burst<Word, Pin: AdcChannel> : Continuous<Word, Pin> {}