Improve documentation. (#32)

* Use `non_exhaustive`.

* Improve docs.

7 files changed, 44 insertions, 46 deletions

diff --git a/src/devices/common.rs b/src/devices/common.rs
index 53cb050..66a6d97 100644
--- a/src/devices/common.rs
+++ b/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)?,
diff --git a/src/devices/features/mod.rs b/src/devices/features/mod.rs
index c24b7b4..e64f25a 100644
--- a/src/devices/features/mod.rs
+++ b/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;
diff --git a/src/devices/features/tier1.rs b/src/devices/features/tier1.rs
index c6aa8cd..3a8beb9 100644
--- a/src/devices/features/tier1.rs
+++ b/src/devices/features/tier1.rs
@@ -1,4 +1,4 @@
-//! Common functions
+//! Features supported on all ADS1x1x devices.
 
 use crate::{ic, Ads1x1x, BitFlags as BF, DataRate12Bit, DataRate16Bit, Error, Register};
 
@@ -6,7 +6,7 @@ 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();
diff --git a/src/devices/features/tier2.rs b/src/devices/features/tier2.rs
index 5f25b41..fe36a72 100644
--- a/src/devices/features/tier2.rs
+++ b/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
diff --git a/src/devices/mode/continuous.rs b/src/devices/mode/continuous.rs
index edc87c2..d514a9a 100644
--- a/src/devices/mode/continuous.rs
+++ b/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.
diff --git a/src/devices/mode/mod.rs b/src/devices/mode/mod.rs
index 670ebe9..356c67a 100644
--- a/src/devices/mode/mod.rs
+++ b/src/devices/mode/mod.rs
@@ -1,4 +1,2 @@
-//! Functions for all devices specific to each operating mode
-
 mod continuous;
 mod oneshot;
diff --git a/src/devices/mode/oneshot.rs b/src/devices/mode/oneshot.rs
index 10cdadb..22b6d51 100644
--- a/src/devices/mode/oneshot.rs
+++ b/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.
     ///