From 7f19f8226e539dc9abcfed2a537a7b9c30df196d Mon Sep 17 00:00:00 2001
From: George Beckstein <donbeckstein@live.com>
Date: Wed, 20 May 2020 06:23:22 -0400
Subject: [PATCH] Revised doxygen comments and fixed code style inconsistencies

---
 drivers/AnalogIn.h          | 16 +++++++++++-----
 drivers/source/AnalogIn.cpp |  8 ++++----
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/drivers/AnalogIn.h b/drivers/AnalogIn.h
index 8fab087cdb..38c1fc130d 100644
--- a/drivers/AnalogIn.h
+++ b/drivers/AnalogIn.h
@@ -72,6 +72,9 @@ public:
     /** Create an AnalogIn, connected to the specified pin
      *
      * @param pinmap reference to structure which holds static pinmap.
+     * @param vref (optional) Reference voltage of this AnalogIn instance (defaults to target.default-adc-vref).
+     *
+     * @note An input voltage at or above the given vref value will produce a 1.0 result when `read` is called
      */
     AnalogIn(const PinMap &pinmap, float vref = MBED_CONF_TARGET_DEFAULT_ADC_VREF);
     AnalogIn(const PinMap &&, float vref = MBED_CONF_TARGET_DEFAULT_ADC_VREF) = delete; // prevent passing of temporary objects
@@ -79,6 +82,9 @@ public:
     /** Create an AnalogIn, connected to the specified pin
      *
      * @param pin AnalogIn pin to connect to
+     * @param vref (optional) Reference voltage of this AnalogIn instance (defaults to target.default-adc-vref).
+     *
+     * @note An input voltage at or above the given vref value will produce a 1.0 result when `read` is called
      */
     AnalogIn(PinName pin, float vref = MBED_CONF_TARGET_DEFAULT_ADC_VREF);
 
@@ -98,9 +104,11 @@ public:
     /**
      * Read the input voltage in volts. The output depends on the target board's
      * ADC reference voltage (typically equal to supply voltage). The ADC reference voltage
-     * sets the maximum voltage the ADC can quantify (ie: Vin == Vref when ADC output == ADC_MAX_VALUE)
+     * sets the maximum voltage the ADC can quantify (ie: ADC output == ADC_MAX_VALUE when Vin == Vref)
      *
-     * The target's ADC reference voltage can be configured by overriding "target.adc_vref"
+     * The target's default ADC reference voltage is determined by the configuration
+     * option target.default-adc_vref. The reference voltage for a particular input
+     * can be manually specified by either the constructor or `AnalogIn::set_reference_voltage`.
      *
      * @returns A floating-point value representing the current input voltage, measured in volts.
      */
@@ -109,8 +117,6 @@ public:
     /**
      * Sets this AnalogIn instance's reference voltage.
      *
-     * Defaults to the configurable MBED_CONF_TARGET_DEFAULT_ADC_VREF setting.
-     *
      * The AnalogIn's reference voltage is used to scale the output when calling AnalogIn::read_volts
      *
      * @param[in] vref New ADC reference voltage for this AnalogIn instance.
@@ -122,7 +128,7 @@ public:
      *
      * @returns A floating-point value representing this AnalogIn's reference voltage, measured in volts.
      */
-    float get_reference_voltage(void);
+    float get_reference_voltage() const;
 
     /** An operator shorthand for read()
      *
diff --git a/drivers/source/AnalogIn.cpp b/drivers/source/AnalogIn.cpp
index cd498f90f7..596d034f19 100644
--- a/drivers/source/AnalogIn.cpp
+++ b/drivers/source/AnalogIn.cpp
@@ -56,17 +56,17 @@ unsigned short AnalogIn::read_u16()
 
 float AnalogIn::read_voltage()
 {
-    return (this->read() * this->_vref);
+    return read() * _vref;
 }
 
 void AnalogIn::set_reference_voltage(float vref)
 {
-    this->_vref = vref;
+    _vref = vref;
 }
 
-float AnalogIn::get_reference_voltage(void)
+float AnalogIn::get_reference_voltage(void) const
 {
-    return this->_vref;
+    return _vref;
 }
 
 } // namespace mbed