added to the time spec documentation

2 files changed, 20 insertions, 9 deletions

diff --git a/host/include/uhd/types/time_spec.hpp b/host/include/uhd/types/time_spec.hpp
index f06d27118..25d9e41d0 100644
--- a/host/include/uhd/types/time_spec.hpp
+++ b/host/include/uhd/types/time_spec.hpp
@@ -28,10 +28,19 @@ namespace uhd{
      * The time_spec_t can be used when setting the time on devices,
      * and for dealing with time stamped samples though the metadata.
      * and for controlling the start of streaming for applicable dsps.
+     *
+     * The fractional seconds are represented in units of nanoseconds,
+     * which provide a clock-domain independent unit of time storage.
+     * The methods "get_ticks" and "set_ticks" can be used to convert
+     * the fractional seconds to and from clock-domain specific units.
+     *
+     * The nanoseconds count is stored as double precision floating point.
+     * This gives the fractional seconds enough precision to unambiguously
+     * specify a clock-tick/sample-count up to rates of several petahertz.
      */
     struct UHD_API time_spec_t{
 
-        //! whole seconds count
+        //! whole/integer seconds count in seconds
         boost::uint32_t secs;
 
         //! fractional seconds count in nano-seconds
@@ -39,24 +48,26 @@ namespace uhd{
 
         /*!
          * Convert the fractional nsecs to clock ticks.
+         * Translation into clock-domain specific units.
          * \param tick_rate the number of ticks per second
-         * \return the number of ticks in this time spec
+         * \return the fractional seconds tick count
          */
         boost::uint32_t get_ticks(double tick_rate) const;
 
         /*!
          * Set the fractional nsecs from clock ticks.
+         * Translation from clock-domain specific units.
          * \param ticks the fractional seconds tick count
          * \param tick_rate the number of ticks per second
          */
         void set_ticks(boost::uint32_t ticks, double tick_rate);
 
         /*!
-         * Create a time_spec_t from seconds and ticks.
-         * \param new_secs the new seconds (default = 0)
-         * \param new_nsecs the new nano-seconds (default = 0)
+         * Create a time_spec_t from whole and fractional seconds.
+         * \param secs the whole/integer seconds count in seconds (default = 0)
+         * \param nsecs the fractional seconds count in nanoseconds (default = 0)
          */
-        time_spec_t(boost::uint32_t new_secs = 0, double new_nsecs = 0);
+        time_spec_t(boost::uint32_t secs = 0, double nsecs = 0);
 
     };
 
diff --git a/host/lib/types.cpp b/host/lib/types.cpp
index 08e41b62f..14f7651d4 100644
--- a/host/lib/types.cpp
+++ b/host/lib/types.cpp
@@ -105,9 +105,9 @@ tx_metadata_t::tx_metadata_t(void){
 /***********************************************************************
  * time spec
  **********************************************************************/
-time_spec_t::time_spec_t(boost::uint32_t new_secs, double new_nsecs){
-    secs = new_secs;
-    nsecs = new_nsecs;
+time_spec_t::time_spec_t(boost::uint32_t secs_, double nsecs_){
+    secs = secs_;
+    nsecs = nsecs_;
 }
 
 boost::uint32_t time_spec_t::get_ticks(double tick_rate) const{