uhd: doxygen comments, moved enum comments, added to metadata for all entities

2 files changed, 43 insertions, 45 deletions

diff --git a/host/include/uhd/types/metadata.hpp b/host/include/uhd/types/metadata.hpp
index 65952941c..3f250d13e 100644
--- a/host/include/uhd/types/metadata.hpp
+++ b/host/include/uhd/types/metadata.hpp
@@ -19,7 +19,6 @@
 #define INCLUDED_UHD_TYPES_METADATA_HPP
 
 #include <uhd/config.hpp>
-#include <boost/cstdint.hpp>
 #include <uhd/types/time_spec.hpp>
 
 namespace uhd{
@@ -30,58 +29,59 @@ namespace uhd{
      * The receive routines will convert IF data headers into metadata.
      */
     struct UHD_API rx_metadata_t{
-        /*!
-         * Time specification:
-         * Set from timestamps on incoming data when provided.
-         */
+        //! Has time specification?
         bool has_time_spec;
+
+        //! Time of the first sample.
         time_spec_t time_spec;
 
         /*!
-         * Fragmentation flag and offset:
+         * Fragmentation flag:
          * Similar to IPv4 fragmentation: http://en.wikipedia.org/wiki/IPv4#Fragmentation_and_reassembly
          * More fragments is true when the input buffer has insufficient size to fit
          * an entire received packet. More fragments will be false for the last fragment.
-         * The fragment offset is the sample number at the start of the receive buffer.
-         * For non-fragmented receives, the fragment offset should always be zero.
          */
         bool more_fragments;
-        size_t fragment_offset;
 
         /*!
-         * Burst flags:
-         * Start of burst will be true for the first packet in the chain.
-         * End of burst will be true for the last packet in the chain.
+         * Fragmentation offset:
+         * The fragment offset is the sample number at the start of the receive buffer.
+         * For non-fragmented receives, the fragment offset should always be zero.
          */
+        size_t fragment_offset;
+
+        //! Start of burst will be true for the first packet in the chain.
         bool start_of_burst;
+
+        //! End of burst will be true for the last packet in the chain.
         bool end_of_burst;
 
         /*!
-         * Error conditions:
-         * - none: no error associated with this metadata
-         * - timeout: no packet received, underlying code timed-out
-         * - late command: a stream command was issued in the past
-         * - broken chain: expected another stream command
-         * - overflow: an internal receive buffer has filled
-         * - bad packet: the buffer was unrecognizable as a vrt packet
+         * The error condition on a receive call.
          *
          * Note: When an overrun occurs in continuous streaming mode,
          * the device will continue to send samples to the host.
          * For other streaming modes, streaming will discontinue
          * until the user issues a new stream command.
          *
-         * Note: The metadata fields have meaning for the following error codes:
+         * The metadata fields have meaning for the following error codes:
          * - none
          * - late command
          * - broken chain
          * - overflow
          */
         enum error_code_t {
+            //! No error associated with this metadata.
             ERROR_CODE_NONE         = 0x0,
+            //! No packet received, implementation timed-out.
             ERROR_CODE_TIMEOUT      = 0x1,
+            //! A stream command was issued in the past.
             ERROR_CODE_LATE_COMMAND = 0x2,
+            //! Expected another stream command.
             ERROR_CODE_BROKEN_CHAIN = 0x4,
+            //! An internal receive buffer has filled.
             ERROR_CODE_OVERFLOW     = 0x8,
+            //! The packet could not be parsed.
             ERROR_CODE_BAD_PACKET   = 0xf
         } error_code;
     };
@@ -93,19 +93,19 @@ namespace uhd{
      */
     struct UHD_API tx_metadata_t{
         /*!
-         * Time specification:
-         * Set has time spec to false to perform a send "now".
-         * Or, set to true, and fill in time spec for a send "at".
+         * Has time specification?
+         * - Set false to send immediately.
+         * - Set true to send at the time specified by time spec.
          */
         bool has_time_spec;
+
+        //! When to send the first sample.
         time_spec_t time_spec;
 
-        /*!
-         * Burst flags:
-         * Set start of burst to true for the first packet in the chain.
-         * Set end of burst to true for the last packet in the chain.
-         */
+        //! Set start of burst to true for the first packet in the chain.
         bool start_of_burst;
+
+        //! Set end of burst to true for the last packet in the chain.
         bool end_of_burst;
 
         /*!
@@ -122,27 +122,27 @@ namespace uhd{
         //! The channel number in a mimo configuration
         size_t channel;
 
-        /*!
-         * Time specification: when the async event occurred.
-         */
+        //! Has time specification?
         bool has_time_spec;
+
+        //! When the async event occurred.
         time_spec_t time_spec;
 
         /*!
-         * Event codes:
-         * - success: a packet was successfully transmitted
-         * - underflow: an internal send buffer has emptied
-         * - sequence error: packet loss between host and device
-         * - time error: packet had time that was late (or too early)
-         * - underflow in packet: underflow occurred inside a packet
-         * - sequence error in burst: packet loss within a burst
+         * The type of event for a receive async message call.
          */
         enum event_code_t {
+            //! A packet was successfully transmitted.
             EVENT_CODE_SUCCESS    = 0x1,
+            //! An internal send buffer has emptied.
             EVENT_CODE_UNDERFLOW  = 0x2,
+            //! Packet loss between host and device.
             EVENT_CODE_SEQ_ERROR  = 0x4,
+            //! Packet had time that was late (or too early).
             EVENT_CODE_TIME_ERROR = 0x8,
+            //! Underflow occurred inside a packet.
             EVENT_CODE_UNDERFLOW_IN_PACKET = 0x10,
+            //! Packet loss within a burst.
             EVENT_CODE_SEQ_ERROR_IN_BURST  = 0x20
         } event_code;
     };
diff --git a/host/include/uhd/types/tune_request.hpp b/host/include/uhd/types/tune_request.hpp
index f80d2cb15..b05ab5cc7 100644
--- a/host/include/uhd/types/tune_request.hpp
+++ b/host/include/uhd/types/tune_request.hpp
@@ -48,21 +48,19 @@ namespace uhd{
          */
         tune_request_t(double target_freq, double lo_off);
 
-        /*!
-         * Policy types for tune arguments:
-         * - None: do not set this argument, use current setting
-         * - Auto: automatically determine the argument's value
-         * - Manual: use the argument's value for the setting
-         */
+        //! Policy options for tunable elements in the RF chain.
         enum policy_t {
+            //! Do not set this argument, use current setting.
             POLICY_NONE   = 'N',
+            //! Automatically determine the argument's value.
             POLICY_AUTO   = 'A',
+            //! Use the argument's value for the setting.
             POLICY_MANUAL = 'M'
         };
 
         /*!
          * The target frequency of the overall chain in Hz.
-         * Use when one of the policies is set to automatic.
+         * Use in conjunction with the automatic policies.
          */
         double target_freq;