Improve documentation. (#32)

* Use `non_exhaustive`.

* Improve docs.

CHANGELOG.md

@@ -49,7 +49,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
   When changing into continuous mode the measurements are started and to stop one
   can simply change into one-shot mode. (This is how the hardware does it anyway).
   The one-shot mode is not affected.
-  When changing the mode an I2C communication error can occur but the unchanged device
+  When changing the mode an I²C communication error can occur but the unchanged device
   can now be retrieved.
 
 ## [0.1.0] - 2018-11-21

README.md

@@ -48,7 +48,7 @@ thermocouples.
 The devices operate either in continuous-conversion mode, or in a
 single-shot mode that automatically powers down after a conversion.
 Single-shot mode significantly reduces current consumption during idle
-periods. Data is transferred through I2C.
+periods. Data is transferred through I²C.
 
 Here is a comparison of the caracteristics of the devices:
 
@@ -70,8 +70,7 @@ Datasheets:
 To use this driver, import this crate and an `embedded_hal` implementation,
 then instantiate the appropriate device.
 In the following examples an instance of the device ADS1013 will be created
-as an example. Other devices can be created with similar methods like:
-`Ads1x1x::new_ads1114(...)`.
+as an example.
 
 Please find additional examples using hardware in this repository: [driver-examples]
 

src/channel.rs

@@ -1,4 +1,5 @@
-//! ADC input channels
+//! ADC input channels.
+
 use crate::{ic, Ads1x1x, BitFlags as BF, Config};
 
 use private::ChannelSelection;

src/devices/common.rs

@@ -1,4 +1,4 @@
-//! Common functions
+//! Common functions.
 
 use crate::{devices::OperatingMode, Ads1x1x, BitFlags, Config, Error, Register};
 
@@ -30,7 +30,7 @@ where
         Ok(())
     }
 
-    /// Read whether a measurement is currently in progress.
+    /// Checks whether a measurement is currently in progress.
     pub fn is_measurement_in_progress(&mut self) -> Result<bool, Error<E>> {
         let config = Config {
             bits: self.read_register(Register::CONFIG)?,

src/devices/features/mod.rs

@@ -1,5 +1,4 @@
-//! Implementation of IC features separated in tiers depending on the hardware
-//! support.
+//! Implementation of IC features separated in tiers depending on the hardware support.
 
 mod tier1;
 mod tier2;

src/devices/features/tier1.rs

@@ -1,12 +1,12 @@
-//! Common functions
+//! Features supported on all ADS1x1x devices.
 
 use crate::{ic, Ads1x1x, BitFlags as BF, DataRate12Bit, DataRate16Bit, Error, Register};
 
 impl<I2C, IC, MODE, E> Ads1x1x<I2C, IC, ic::Resolution12Bit, MODE>
 where
     I2C: embedded_hal::i2c::I2c<Error = E>,
 {
-    /// Set data rate
+    /// Sets the data rate.
     pub fn set_data_rate(&mut self, rate: DataRate12Bit) -> Result<(), Error<E>> {
         use crate::DataRate12Bit as DR;
         let cfg = self.config.clone();
@@ -29,7 +29,7 @@ impl<I2C, IC, MODE, E> Ads1x1x<I2C, IC, ic::Resolution16Bit, MODE>
 where
     I2C: embedded_hal::i2c::I2c<Error = E>,
 {
-    /// Set data rate
+    /// Sets the data rate.
     pub fn set_data_rate(&mut self, rate: DataRate16Bit) -> Result<(), Error<E>> {
         use crate::DataRate16Bit as DR;
         let cfg = self.config.clone();

src/devices/features/tier2.rs

@@ -1,6 +1,4 @@
-//! Tier 2 features.
-//!
-//! These are the features included only in ADS1x14, ADS1x15
+//! Features only supported by ADS1x14 and ADS1x15 devices.
 
 use crate::{
     conversion, ic, Ads1x1x, BitFlags as BF, ComparatorLatching, ComparatorMode,
@@ -13,9 +11,9 @@ where
     IC: ic::Tier2Features,
     CONV: conversion::ConvertThreshold<E>,
 {
-    /// Set the input voltage measurable range
+    /// Sets the input voltage measurable range.
     ///
-    /// This configures the programmable gain amplifier and determines the measurable input voltage range.
+    /// This configures the programmable gain amplifier (PGA) and determines the measurable input voltage range.
     pub fn set_full_scale_range(&mut self, range: FullScaleRange) -> Result<(), Error<E>> {
         use crate::FullScaleRange as FSR;
         let cfg = self.config.clone();
@@ -47,29 +45,31 @@ where
         Ok(())
     }
 
-    /// Set raw comparator lower threshold
+    /// Sets the raw comparator lower threshold.
+    ///
+    /// The voltage that these values correspond to must be calculated using the
+    /// full-scale range ([`FullScaleRange`]) selected.
     ///
     /// The input value must be within `[2047..-2048]` for 12-bit devices (`ADS101x`)
-    /// and within `[32767..-32768]` for 16-bit devices (`ADS111x`). The voltage that
-    /// these values correspond to must be calculated using the full-scale range
-    /// selected. See [`FullScaleRange`](enum.FullScaleRange.html).
+    /// and within `[32767..-32768]` for 16-bit devices (`ADS111x`).
     pub fn set_low_threshold_raw(&mut self, value: i16) -> Result<(), Error<E>> {
         let register_value = CONV::convert_threshold(value)?;
         self.write_register(Register::LOW_TH, register_value)
     }
 
-    /// Set raw comparator upper threshold
+    /// Sets the raw comparator upper threshold.
+    ///
+    /// The voltage that these values correspond to must be calculated using the
+    /// full-scale range ([`FullScaleRange`]) selected.
     ///
     /// The input value must be within `[2047..-2048]` for 12-bit devices (`ADS101x`)
-    /// and within `[32767..-32768]` for 16-bit devices (`ADS111x`). The voltage that
-    /// these values correspond to must be calculated using the full-scale range
-    /// selected. See [`FullScaleRange`](enum.FullScaleRange.html).
+    /// and within `[32767..-32768]` for 16-bit devices (`ADS111x`).
     pub fn set_high_threshold_raw(&mut self, value: i16) -> Result<(), Error<E>> {
         let register_value = CONV::convert_threshold(value)?;
         self.write_register(Register::HIGH_TH, register_value)
     }
 
-    /// Set comparator mode
+    /// Sets the comparator mode.
     pub fn set_comparator_mode(&mut self, mode: ComparatorMode) -> Result<(), Error<E>> {
         let config = match mode {
             ComparatorMode::Traditional => self.config.with_low(BF::COMP_MODE),
@@ -80,7 +80,7 @@ where
         Ok(())
     }
 
-    /// Set comparator polarity
+    /// Sets the comparator polarity.
     pub fn set_comparator_polarity(
         &mut self,
         polarity: ComparatorPolarity,
@@ -94,7 +94,7 @@ where
         Ok(())
     }
 
-    /// Set comparator latching
+    /// Sets the comparator latching.
     pub fn set_comparator_latching(
         &mut self,
         latching: ComparatorLatching,
@@ -108,9 +108,9 @@ where
         Ok(())
     }
 
-    /// Activate comparator and set the alert queue
+    /// Activates the comparator and sets the alert queue.
     ///
-    /// The comparator can be disabled with [`disable_comparator()`](struct.Ads1x1x.html#method.disable_comparator)
+    /// The comparator can be disabled with [`disable_comparator`](Self::disable_comparator).
     pub fn set_comparator_queue(&mut self, queue: ComparatorQueue) -> Result<(), Error<E>> {
         let config = match queue {
             ComparatorQueue::One => self.config.with_low(BF::COMP_QUE1).with_low(BF::COMP_QUE0),
@@ -122,11 +122,12 @@ where
         Ok(())
     }
 
-    /// Disable comparator (default)
+    /// Disables the comparator. (default)
+    ///
+    /// This sets the ALERT/RDY pin to high-impedance.
     ///
-    /// This will set the ALERT/RDY pin to high-impedance.
-    /// The comparator can be enabled by setting the comparator queue.
-    /// See [`set_comparator_queue()`](struct.Ads1x1x.html#method.set_comparator_queue)
+    /// The comparator can be enabled by setting the comparator queue using
+    /// the [`set_comparator_queue`](Self::set_comparator_queue) method.
     pub fn disable_comparator(&mut self) -> Result<(), Error<E>> {
         let config = self
             .config
@@ -137,13 +138,12 @@ where
         Ok(())
     }
 
-    /// Use the ALERT/RDY pin as conversion-ready pin.
+    /// Enables the ALERT/RDY pin as conversion-ready function.
     ///
-    /// This the ALERT/RDY pin outputs the OS bit when in OneShot mode, and
-    /// provides a continuous-conversion ready pulse when in
-    /// continuous-conversion mode.
+    /// When in one-shot mode, this makes the ALERT/RDY pin output the OS bit,
+    /// in continuous-conversion mode, provides a continuous-conversion ready pulse.
     ///
-    /// When calling this the comparator will be reset to default and the thresholds will be cleared.
+    /// When calling this the comparator will be reset to default and any thresholds will be cleared.
     pub fn use_alert_rdy_pin_as_ready(&mut self) -> Result<(), Error<E>> {
         if self.config
             != self

src/devices/mode/continuous.rs

@@ -1,4 +1,4 @@
-//! Continuous measurement mode
+//! Continuous measurement mode.
 
 use crate::{
     conversion, devices::OperatingMode, mode, Ads1x1x, ChannelId, Error, ModeChangeError, Register,
@@ -10,7 +10,7 @@ where
     I2C: embedded_hal::i2c::I2c<Error = E>,
     CONV: conversion::ConvertMeasurement,
 {
-    /// Change operating mode to OneShot
+    /// Changes to one-shot operating mode.
     pub fn into_one_shot(
         mut self,
     ) -> Result<Ads1x1x<I2C, IC, CONV, mode::OneShot>, ModeChangeError<E, Self>> {
@@ -29,13 +29,13 @@ where
         })
     }
 
-    /// Read the most recent measurement
+    /// Reads the most recent measurement.
     pub fn read(&mut self) -> Result<i16, Error<E>> {
         let value = self.read_register(Register::CONVERSION)?;
         Ok(CONV::convert_measurement(value))
     }
 
-    /// Select the channel for measurements.
+    /// Selects the channel used for measurements.
     ///
     /// Note that when changing the channel in continuous conversion mode, the
     /// ongoing conversion will be completed.

src/devices/mode/mod.rs

@@ -1,4 +1,2 @@
-//! Functions for all devices specific to each operating mode
-
 mod continuous;
 mod oneshot;

src/devices/mode/oneshot.rs

@@ -1,16 +1,18 @@
-//! Common functions
+//! One-shot measurement mode.
+
+use core::marker::PhantomData;
+
 use crate::{
     conversion, devices::OperatingMode, mode, Ads1x1x, BitFlags, ChannelId, Config, Error,
     ModeChangeError, Register,
 };
-use core::marker::PhantomData;
 
 impl<I2C, IC, CONV, E> Ads1x1x<I2C, IC, CONV, mode::OneShot>
 where
     I2C: embedded_hal::i2c::I2c<Error = E>,
     CONV: conversion::ConvertMeasurement,
 {
-    /// Change operating mode to Continuous
+    /// Changes to continuous operating mode.
     pub fn into_continuous(
         mut self,
     ) -> Result<Ads1x1x<I2C, IC, CONV, mode::Continuous>, ModeChangeError<E, Self>> {
@@ -40,13 +42,12 @@ where
     I2C: embedded_hal::i2c::I2c<Error = E>,
     CONV: conversion::ConvertMeasurement,
 {
-    /// Request that the ADC begin a conversion on the specified channel.
+    /// Requests that the ADC begins a conversion on the specified channel.
     ///
     /// The output value will be within `[2047..-2048]` for 12-bit devices
     /// (`ADS101x`) and within `[32767..-32768]` for 16-bit devices (`ADS111x`).
     /// The voltage that these values correspond to must be calculated using
-    /// the full-scale range selected.
-    /// See [`FullScaleRange`](enum.FullScaleRange.html).
+    /// the full-scale range ([`FullScaleRange`](crate::FullScaleRange)) selected.
     ///
     /// Returns `nb::Error::WouldBlock` while a measurement is in progress.
     ///

src/ic.rs

@@ -1,8 +1,10 @@
 /// ICs
 use crate::private;
 
-pub struct Resolution12Bit(pub(crate) ());
-pub struct Resolution16Bit(pub(crate) ());
+#[non_exhaustive]
+pub struct Resolution12Bit;
+#[non_exhaustive]
+pub struct Resolution16Bit;
 
 macro_rules! ic_marker {
     ($name:ident) => {

src/lib.rs

@@ -36,7 +36,7 @@
 //! [`disable_comparator()`]: struct.Ads1x1x.html#method.disable_comparator
 //! [`use_alert_rdy_pin_as_ready()`]: struct.Ads1x1x.html#method.use_alert_rdy_pin_as_ready
 //!
-//! ## The devices
+//! # The devices
 //!
 //! The devices are precision, low power, 12/16-bit analog-to-digital
 //! converters (ADC) that provide all features necessary to measure the most
@@ -55,7 +55,7 @@
 //! The devices operate either in continuous-conversion mode, or in a
 //! single-shot mode that automatically powers down after a conversion.
 //! Single-shot mode significantly reduces current consumption during idle
-//! periods. Data is transferred through I2C.
+//! periods. Data is transferred through I²C.
 //!
 //! Here is a comparison of the caracteristics of the devices:
 //!
@@ -72,19 +72,17 @@
 //! - [ADS101x](http://www.ti.com/lit/ds/symlink/ads1015.pdf)
 //! - [ADS111x](http://www.ti.com/lit/ds/symlink/ads1115.pdf)
 //!
-//! ## Usage examples (see also examples folder)
+//! # Examples
 //!
 //! To use this driver, import this crate and an `embedded_hal` implementation,
 //! then instantiate the appropriate device.
-//! In the following examples an instance of the device ADS1013 will be created
-//! as an example. Other devices can be created with similar methods like:
-//! `Ads1x1x::new_ads1114(...)`.
+//! In the following examples an instance of the device ADS1013 will be created.
 //!
 //! Please find additional examples using hardware in this repository: [driver-examples]
 //!
 //! [driver-examples]: https://github.com/eldruin/driver-examples
 //!
-//! ### Create a driver instance for an ADS1013 with the default address.
+//! ## Creating a Driver Instance for an ADS1013
 //!
 //! ```no_run
 //! use linux_embedded_hal::I2cdev;
@@ -98,7 +96,7 @@
 //! let dev = adc.destroy_ads1013();
 //! ```
 //!
-//! ### Create a driver instance for an ADS1013 with the ADDR pin connected to SDA.
+//! ## Creating a driver instance for an ADS1013 with the ADDR pin connected to SDA.
 //!
 //! ```no_run
 //! use linux_embedded_hal::I2cdev;
@@ -108,7 +106,8 @@
 //! let adc = Ads1x1x::new_ads1013(dev, TargetAddr::Sda);
 //! ```
 //!
-//! ### Make a one-shot measurement
+//! ## Taking a One-Shot Measurement
+//!
 //! ```no_run
 //! use ads1x1x::{channel, Ads1x1x, TargetAddr};
 //! use linux_embedded_hal::I2cdev;
@@ -121,7 +120,7 @@
 //! let _dev = adc.destroy_ads1013(); // get I2C device back
 //! ```
 //!
-//! ### Change into continuous conversion mode and read the last measurement
+//! ## Changing to Continuous Conversion Mode and Reading the Last Measurement
 //!
 //! Changing the mode may fail in case there was a communication error.
 //! In this case, you can retrieve the unchanged device from the error type.
@@ -133,7 +132,9 @@
 //! let dev = I2cdev::new("/dev/i2c-1").unwrap();
 //! let adc = Ads1x1x::new_ads1013(dev, TargetAddr::default());
 //! match adc.into_continuous() {
-//!     Err(ModeChangeError::I2C(e, adc)) => /* mode change failed handling */ panic!(),
+//!     Err(ModeChangeError::I2C(e, adc)) => {
+//!         panic!("Mode change failed: {e}")
+//!     },
 //!     Ok(mut adc) => {
 //!         let measurement = adc.read().unwrap();
 //!         // ...
@@ -142,7 +143,7 @@
 //! ```
 //!
 //!
-//! ### Set the data rate
+//! ## Setting the Data Rate
 //! For 12-bit devices, the available data rates are given by `DataRate12Bit`.
 //! For 16-bit devices, the available data rates are given by `DataRate16Bit`.
 //!
@@ -155,7 +156,8 @@
 //! adc.set_data_rate(DataRate16Bit::Sps860).unwrap();
 //! ```
 //!
-//! ### Configure the comparator
+//! ## Configuring the Comparator
+//!
 //! Configure the comparator to assert when the voltage drops below -1.5V
 //! or goes above 1.5V in at least two consecutive conversions. Then the
 //! ALERT/RDY pin will be set high and it will be kept so until the