usrp: added docstrings to single and multi usrp for undocumented methods

2 files changed, 432 insertions, 4 deletions

diff --git a/host/include/uhd/usrp/multi_usrp.hpp b/host/include/uhd/usrp/multi_usrp.hpp
index dcec0c515..6adba85bd 100644
--- a/host/include/uhd/usrp/multi_usrp.hpp
+++ b/host/include/uhd/usrp/multi_usrp.hpp
@@ -170,8 +170,16 @@ public:
      * The subdev spec maps a physical part of a daughter-board to a channel number.
      * Set the subdev spec before calling into any methods with a channel number.
      * The subdev spec must be the same size across all motherboards.
+     * \param spec the new subdevice specification
+     * \param mboard the motherboard index 0 to M-1
      */
     virtual void set_rx_subdev_spec(const uhd::usrp::subdev_spec_t &spec, size_t mboard) = 0;
+
+    /*!
+     * Get the RX subdevice specification.
+     * \param mboard the motherboard index 0 to M-1
+     * \return the subdevice specification in use
+     */
     virtual uhd::usrp::subdev_spec_t get_rx_subdev_spec(size_t mboard) = 0;
 
     /*!
@@ -181,36 +189,136 @@ public:
      */
     virtual size_t get_rx_num_channels(void) = 0;
 
+    /*!
+     * Get the name of the RX subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return the subdevice name
+     */
     virtual std::string get_rx_subdev_name(size_t chan) = 0;
 
+    /*!
+     * Set the RX sample rate across all channels.
+     * \param rate the rate in Sps
+     */
     virtual void set_rx_rate(double rate) = 0;
+
+    /*!
+     * Gets the RX sample rate for all channels.
+     * \return the rate in Sps
+     */
     virtual double get_rx_rate(void) = 0;
 
+    /*!
+     * Set the RX center frequency.
+     * \param freq the frequency in Hz
+     * \param chan the channel index 0 to N-1
+     * \return a tune result object
+     */
     virtual tune_result_t set_rx_freq(double freq, size_t chan) = 0;
+
+    /*!
+     * Set the RX center frequency.
+     * \param freq the frequency in Hz
+     * \param lo_off an LO offset in Hz
+     * \param chan the channel index 0 to N-1
+     * \return a tune result object
+     */
     virtual tune_result_t set_rx_freq(double freq, double lo_off, size_t chan) = 0;
+
+    /*!
+     * Get the RX center frequency.
+     * \param chan the channel index 0 to N-1
+     * \return the frequency in Hz
+     */
     virtual double get_rx_freq(size_t chan) = 0;
+
+    /*!
+     * Get the RX center frequency range.
+     * \param chan the channel index 0 to N-1
+     * \return a frequency range object
+     */
     virtual freq_range_t get_rx_freq_range(size_t chan) = 0;
 
+    /*!
+     * Set the RX gain:
+     * Distribute among gain elements in the RX path.
+     * \param gain the gain in dB
+     * \param chan the channel index 0 to N-1
+     */
     virtual void set_rx_gain(float gain, size_t chan) = 0;
+
+    /*!
+     * Get the RX gain:
+     * Summation of gain elements in the RX path.
+     * \param chan the channel index 0 to N-1
+     * \return the gain in dB
+     */
     virtual float get_rx_gain(size_t chan) = 0;
+
+    /*!
+     * Get the RX gain range.
+     * \param chan the channel index 0 to N-1
+     * \return a gain range object
+     */
     virtual gain_range_t get_rx_gain_range(size_t chan) = 0;
 
+    /*!
+     * Select the RX antenna on the subdevice.
+     * \param ant the antenna name
+     * \param chan the channel index 0 to N-1
+     */
     virtual void set_rx_antenna(const std::string &ant, size_t chan) = 0;
+
+    /*!
+     * Get the selected RX antenna on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return the antenna name
+     */
     virtual std::string get_rx_antenna(size_t chan) = 0;
+
+    /*!
+     * Get a list of possible RX antennas on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return a vector of antenna names
+     */
     virtual std::vector<std::string> get_rx_antennas(size_t chan) = 0;
 
+    /*!
+     * Get the locked status of the LO on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return true for locked
+     */
     virtual bool get_rx_lo_locked(size_t chan) = 0;
 
+    /*!
+     * Set the RX bandwidth on the subdevice.
+     * \param bandwidth the bandwidth in Hz
+     * \param chan the channel index 0 to N-1
+     */
     virtual void set_rx_bandwidth(double bandwidth, size_t chan) = 0;
+
+    /*!
+     * Get the RX bandwidth on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return the bandwidth in Hz
+     */
     virtual double get_rx_bandwidth(size_t chan) = 0;
 
     /*!
-     * Read the RSSI value from a usrp device.
-     * Or throw if the dboard does not support an RSSI readback.
+     * Read the RSSI value on the RX subdevice.
+     * \param chan the channel index 0 to N-1
      * \return the rssi in dB
+     * \throw exception if RSSI readback not supported
      */
     virtual float read_rssi(size_t chan) = 0;
 
+    /*!
+     * Get the dboard interface object for the RX subdevice.
+     * The dboard interface gives access to GPIOs, SPI, I2C, low-speed ADC and DAC.
+     * Use at your own risk!
+     * \param chan the channel index 0 to N-1
+     * \return the dboard interface sptr
+     */
     virtual dboard_iface::sptr get_rx_dboard_iface(size_t chan) = 0;
 
     /*******************************************************************
@@ -221,8 +329,16 @@ public:
      * The subdev spec maps a physical part of a daughter-board to a channel number.
      * Set the subdev spec before calling into any methods with a channel number.
      * The subdev spec must be the same size across all motherboards.
+     * \param spec the new subdevice specification
+     * \param mboard the motherboard index 0 to M-1
      */
     virtual void set_tx_subdev_spec(const uhd::usrp::subdev_spec_t &spec, size_t mboard) = 0;
+
+    /*!
+     * Get the TX subdevice specification.
+     * \param mboard the motherboard index 0 to M-1
+     * \return the subdevice specification in use
+     */
     virtual uhd::usrp::subdev_spec_t get_tx_subdev_spec(size_t mboard) = 0;
 
     /*!
@@ -232,29 +348,128 @@ public:
      */
     virtual size_t get_tx_num_channels(void) = 0;
 
+    /*!
+     * Get the name of the TX subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return the subdevice name
+     */
     virtual std::string get_tx_subdev_name(size_t chan) = 0;
 
+    /*!
+     * Set the TX sample rate across all channels.
+     * \param rate the rate in Sps
+     */
     virtual void set_tx_rate(double rate) = 0;
+
+    /*!
+     * Gets the TX sample rate for all channels.
+     * \return the rate in Sps
+     */
     virtual double get_tx_rate(void) = 0;
 
+    /*!
+     * Set the TX center frequency.
+     * \param freq the frequency in Hz
+     * \param chan the channel index 0 to N-1
+     * \return a tune result object
+     */
     virtual tune_result_t set_tx_freq(double freq, size_t chan) = 0;
+
+    /*!
+     * Set the TX center frequency.
+     * \param freq the frequency in Hz
+     * \param lo_off an LO offset in Hz
+     * \param chan the channel index 0 to N-1
+     * \return a tune result object
+     */
     virtual tune_result_t set_tx_freq(double freq, double lo_off, size_t chan) = 0;
+
+    /*!
+     * Get the TX center frequency.
+     * \param chan the channel index 0 to N-1
+     * \return the frequency in Hz
+     */
     virtual double get_tx_freq(size_t chan) = 0;
+
+    /*!
+     * Get the TX center frequency range.
+     * \param chan the channel index 0 to N-1
+     * \return a frequency range object
+     */
     virtual freq_range_t get_tx_freq_range(size_t chan) = 0;
 
+    /*!
+     * Set the TX gain:
+     * Distribute among gain elements in the TX path.
+     * \param gain the gain in dB
+     * \param chan the channel index 0 to N-1
+     */
     virtual void set_tx_gain(float gain, size_t chan) = 0;
+
+    /*!
+     * Get the TX gain:
+     * Summation of gain elements in the TX path.
+     * \param chan the channel index 0 to N-1
+     * \return the gain in dB
+     */
     virtual float get_tx_gain(size_t chan) = 0;
+
+    /*!
+     * Get the TX gain range.
+     * \param chan the channel index 0 to N-1
+     * \return a gain range object
+     */
     virtual gain_range_t get_tx_gain_range(size_t chan) = 0;
 
+    /*!
+     * Select the TX antenna on the subdevice.
+     * \param ant the antenna name
+     * \param chan the channel index 0 to N-1
+     */
     virtual void set_tx_antenna(const std::string &ant, size_t chan) = 0;
+
+    /*!
+     * Get the selected TX antenna on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return the antenna name
+     */
     virtual std::string get_tx_antenna(size_t chan) = 0;
+
+    /*!
+     * Get a list of possible TX antennas on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return a vector of antenna names
+     */
     virtual std::vector<std::string> get_tx_antennas(size_t chan) = 0;
 
+    /*!
+     * Get the locked status of the LO on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return true for locked
+     */
     virtual bool get_tx_lo_locked(size_t chan) = 0;
 
+    /*!
+     * Set the TX bandwidth on the subdevice.
+     * \param bandwidth the bandwidth in Hz
+     * \param chan the channel index 0 to N-1
+     */
     virtual void set_tx_bandwidth(double bandwidth, size_t chan) = 0;
+
+    /*!
+     * Get the TX bandwidth on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return the bandwidth in Hz
+     */
     virtual double get_tx_bandwidth(size_t chan) = 0;
 
+    /*!
+     * Get the dboard interface object for the TX subdevice.
+     * The dboard interface gives access to GPIOs, SPI, I2C, low-speed ADC and DAC.
+     * Use at your own risk!
+     * \param chan the channel index 0 to N-1
+     * \return the dboard interface sptr
+     */
     virtual dboard_iface::sptr get_tx_dboard_iface(size_t chan) = 0;
 };
 
diff --git a/host/include/uhd/usrp/single_usrp.hpp b/host/include/uhd/usrp/single_usrp.hpp
index 9b2fd7ccf..74a978f05 100644
--- a/host/include/uhd/usrp/single_usrp.hpp
+++ b/host/include/uhd/usrp/single_usrp.hpp
@@ -120,40 +120,147 @@ public:
      * Set the RX subdevice specification:
      * The subdev spec maps a physical part of a daughter-board to a channel number.
      * Set the subdev spec before calling into any methods with a channel number.
+     * The subdev spec must be the same size across all motherboards.
+     * \param spec the new subdevice specification
      */
     virtual void set_rx_subdev_spec(const uhd::usrp::subdev_spec_t &spec) = 0;
+
+    /*!
+     * Get the RX subdevice specification.
+     * \return the subdevice specification in use
+     */
     virtual uhd::usrp::subdev_spec_t get_rx_subdev_spec(void) = 0;
 
+    /*!
+     * Get the name of the RX subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return the subdevice name
+     */
     virtual std::string get_rx_subdev_name(size_t chan = 0) = 0;
 
+    /*!
+     * Set the RX sample rate across all channels.
+     * \param rate the rate in Sps
+     */
     virtual void set_rx_rate(double rate) = 0;
+
+    /*!
+     * Gets the RX sample rate for all channels.
+     * \return the rate in Sps
+     */
     virtual double get_rx_rate(void) = 0;
 
+    /*!
+     * Set the RX center frequency.
+     * \param freq the frequency in Hz
+     * \param chan the channel index 0 to N-1
+     * \return a tune result object
+     */
     virtual tune_result_t set_rx_freq(double freq, size_t chan = 0) = 0;
+
+    /*!
+     * Set the RX center frequency.
+     * \param freq the frequency in Hz
+     * \param lo_off an LO offset in Hz
+     * \param chan the channel index 0 to N-1
+     * \return a tune result object
+     */
     virtual tune_result_t set_rx_freq(double freq, double lo_off, size_t chan = 0) = 0;
+
+    /*!
+     * Get the RX center frequency.
+     * \param chan the channel index 0 to N-1
+     * \return the frequency in Hz
+     */
     virtual double get_rx_freq(size_t chan = 0) = 0;
+
+    /*!
+     * Get the RX center frequency range.
+     * \param chan the channel index 0 to N-1
+     * \return a frequency range object
+     */
     virtual freq_range_t get_rx_freq_range(size_t chan = 0) = 0;
 
+    /*!
+     * Set the RX gain:
+     * Distribute among gain elements in the RX path.
+     * \param gain the gain in dB
+     * \param chan the channel index 0 to N-1
+     */
     virtual void set_rx_gain(float gain, size_t chan = 0) = 0;
+
+    /*!
+     * Get the RX gain:
+     * Summation of gain elements in the RX path.
+     * \param chan the channel index 0 to N-1
+     * \return the gain in dB
+     */
     virtual float get_rx_gain(size_t chan = 0) = 0;
+
+    /*!
+     * Get the RX gain range.
+     * \param chan the channel index 0 to N-1
+     * \return a gain range object
+     */
     virtual gain_range_t get_rx_gain_range(size_t chan = 0) = 0;
 
+    /*!
+     * Select the RX antenna on the subdevice.
+     * \param ant the antenna name
+     * \param chan the channel index 0 to N-1
+     */
     virtual void set_rx_antenna(const std::string &ant, size_t chan = 0) = 0;
+
+    /*!
+     * Get the selected RX antenna on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return the antenna name
+     */
     virtual std::string get_rx_antenna(size_t chan = 0) = 0;
+
+    /*!
+     * Get a list of possible RX antennas on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return a vector of antenna names
+     */
     virtual std::vector<std::string> get_rx_antennas(size_t chan = 0) = 0;
 
+    /*!
+     * Get the locked status of the LO on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return true for locked
+     */
     virtual bool get_rx_lo_locked(size_t chan = 0) = 0;
 
+    /*!
+     * Set the RX bandwidth on the subdevice.
+     * \param bandwidth the bandwidth in Hz
+     * \param chan the channel index 0 to N-1
+     */
     virtual void set_rx_bandwidth(double bandwidth, size_t chan = 0) = 0;
+
+    /*!
+     * Get the RX bandwidth on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return the bandwidth in Hz
+     */
     virtual double get_rx_bandwidth(size_t chan = 0) = 0;
 
     /*!
-     * Read the RSSI value from a usrp device.
-     * Or throw if the dboard does not support an RSSI readback.
+     * Read the RSSI value on the RX subdevice.
+     * \param chan the channel index 0 to N-1
      * \return the rssi in dB
+     * \throw exception if RSSI readback not supported
      */
     virtual float read_rssi(size_t chan = 0) = 0;
 
+    /*!
+     * Get the dboard interface object for the RX subdevice.
+     * The dboard interface gives access to GPIOs, SPI, I2C, low-speed ADC and DAC.
+     * Use at your own risk!
+     * \param chan the channel index 0 to N-1
+     * \return the dboard interface sptr
+     */
     virtual dboard_iface::sptr get_rx_dboard_iface(size_t chan = 0) = 0;
 
     /*******************************************************************
@@ -163,33 +270,139 @@ public:
      * Set the TX subdevice specification:
      * The subdev spec maps a physical part of a daughter-board to a channel number.
      * Set the subdev spec before calling into any methods with a channel number.
+     * The subdev spec must be the same size across all motherboards.
+     * \param spec the new subdevice specification
      */
     virtual void set_tx_subdev_spec(const uhd::usrp::subdev_spec_t &spec) = 0;
+
+    /*!
+     * Get the TX subdevice specification.
+     * \return the subdevice specification in use
+     */
     virtual uhd::usrp::subdev_spec_t get_tx_subdev_spec(void) = 0;
 
+    /*!
+     * Get the name of the TX subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return the subdevice name
+     */
     virtual std::string get_tx_subdev_name(size_t chan = 0) = 0;
 
+    /*!
+     * Set the TX sample rate across all channels.
+     * \param rate the rate in Sps
+     */
     virtual void set_tx_rate(double rate) = 0;
+
+    /*!
+     * Gets the TX sample rate for all channels.
+     * \return the rate in Sps
+     */
     virtual double get_tx_rate(void) = 0;
 
+    /*!
+     * Set the TX center frequency.
+     * \param freq the frequency in Hz
+     * \param chan the channel index 0 to N-1
+     * \return a tune result object
+     */
     virtual tune_result_t set_tx_freq(double freq, size_t chan = 0) = 0;
+
+    /*!
+     * Set the TX center frequency.
+     * \param freq the frequency in Hz
+     * \param lo_off an LO offset in Hz
+     * \param chan the channel index 0 to N-1
+     * \return a tune result object
+     */
     virtual tune_result_t set_tx_freq(double freq, double lo_off, size_t chan = 0) = 0;
+
+    /*!
+     * Get the TX center frequency.
+     * \param chan the channel index 0 to N-1
+     * \return the frequency in Hz
+     */
     virtual double get_tx_freq(size_t chan = 0) = 0;
+
+    /*!
+     * Get the TX center frequency range.
+     * \param chan the channel index 0 to N-1
+     * \return a frequency range object
+     */
     virtual freq_range_t get_tx_freq_range(size_t chan = 0) = 0;
 
+    /*!
+     * Set the TX gain:
+     * Distribute among gain elements in the TX path.
+     * \param gain the gain in dB
+     * \param chan the channel index 0 to N-1
+     */
     virtual void set_tx_gain(float gain, size_t chan = 0) = 0;
+
+    /*!
+     * Get the TX gain:
+     * Summation of gain elements in the TX path.
+     * \param chan the channel index 0 to N-1
+     * \return the gain in dB
+     */
     virtual float get_tx_gain(size_t chan = 0) = 0;
+
+    /*!
+     * Get the TX gain range.
+     * \param chan the channel index 0 to N-1
+     * \return a gain range object
+     */
     virtual gain_range_t get_tx_gain_range(size_t chan = 0) = 0;
 
+    /*!
+     * Select the TX antenna on the subdevice.
+     * \param ant the antenna name
+     * \param chan the channel index 0 to N-1
+     */
     virtual void set_tx_antenna(const std::string &ant, size_t chan = 0) = 0;
+
+    /*!
+     * Get the selected TX antenna on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return the antenna name
+     */
     virtual std::string get_tx_antenna(size_t chan = 0) = 0;
+
+    /*!
+     * Get a list of possible TX antennas on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return a vector of antenna names
+     */
     virtual std::vector<std::string> get_tx_antennas(size_t chan = 0) = 0;
 
+    /*!
+     * Get the locked status of the LO on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return true for locked
+     */
     virtual bool get_tx_lo_locked(size_t chan = 0) = 0;
 
+    /*!
+     * Set the TX bandwidth on the subdevice.
+     * \param bandwidth the bandwidth in Hz
+     * \param chan the channel index 0 to N-1
+     */
     virtual void set_tx_bandwidth(double bandwidth, size_t chan = 0) = 0;
+
+    /*!
+     * Get the TX bandwidth on the subdevice.
+     * \param chan the channel index 0 to N-1
+     * \return the bandwidth in Hz
+     */
     virtual double get_tx_bandwidth(size_t chan = 0) = 0;
 
+    /*!
+     * Get the dboard interface object for the TX subdevice.
+     * The dboard interface gives access to GPIOs, SPI, I2C, low-speed ADC and DAC.
+     * Use at your own risk!
+     * \param chan the channel index 0 to N-1
+     * \return the dboard interface sptr
+     */
     virtual dboard_iface::sptr get_tx_dboard_iface(size_t chan = 0) = 0;
 };