From 0edd5527161809dfbc0c76e39c462e3a4f00beb7 Mon Sep 17 00:00:00 2001 From: Markus Reiter Date: Sat, 23 Nov 2024 22:49:30 +0100 Subject: Improve documentation. (#32) * Use `non_exhaustive`. * Improve docs. --- src/devices/common.rs | 4 ++-- src/devices/features/mod.rs | 3 +-- src/devices/features/tier1.rs | 6 ++--- src/devices/features/tier2.rs | 54 +++++++++++++++++++++--------------------- src/devices/mode/continuous.rs | 8 +++---- src/devices/mode/mod.rs | 2 -- src/devices/mode/oneshot.rs | 13 +++++----- 7 files changed, 44 insertions(+), 46 deletions(-) (limited to 'src/devices') 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> { 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 Ads1x1x where I2C: embedded_hal::i2c::I2c, { - /// Set data rate + /// Sets the data rate. pub fn set_data_rate(&mut self, rate: DataRate12Bit) -> Result<(), Error> { use crate::DataRate12Bit as DR; let cfg = self.config.clone(); @@ -29,7 +29,7 @@ impl Ads1x1x where I2C: embedded_hal::i2c::I2c, { - /// Set data rate + /// Sets the data rate. pub fn set_data_rate(&mut self, rate: DataRate16Bit) -> Result<(), Error> { 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, { - /// 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> { 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> { 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> { 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> { 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> { 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> { 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> { 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, CONV: conversion::ConvertMeasurement, { - /// Change operating mode to OneShot + /// Changes to one-shot operating mode. pub fn into_one_shot( mut self, ) -> Result, ModeChangeError> { @@ -29,13 +29,13 @@ where }) } - /// Read the most recent measurement + /// Reads the most recent measurement. pub fn read(&mut self) -> Result> { 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 Ads1x1x where I2C: embedded_hal::i2c::I2c, CONV: conversion::ConvertMeasurement, { - /// Change operating mode to Continuous + /// Changes to continuous operating mode. pub fn into_continuous( mut self, ) -> Result, ModeChangeError> { @@ -40,13 +42,12 @@ where I2C: embedded_hal::i2c::I2c, 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. /// -- cgit v1.2.3-54-g00ecf