Improve docs.

Author: reitermarkus

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,10 @@
-//! Common functions
-
 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 +27,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 included in ADS1x14, ADS1x15.
 
 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 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,20 @@
-//! 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.
+    ///
+    /// On error, returns a pair of the error and the current instance.
     pub fn into_continuous(
         mut self,
     ) -> Result<Ads1x1x<I2C, IC, CONV, mode::Continuous>, ModeChangeError<E, Self>> {
@@ -40,13 +44,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.
     ///