[vlc-commits] mtime: clean up Doxygen

[Rémi Denis-Courmont]

vlc | branch: master | Rémi Denis-Courmont <remi at remlab.net> | Wed May  2 18:55:52 2018 +0300| [84ece839e0786eef712770ef8ec40e6304d7655a] | committer: Rémi Denis-Courmont

mtime: clean up Doxygen

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=84ece839e0786eef712770ef8ec40e6304d7655a
---

 include/vlc_mtime.h | 77 ++++++++++++++++++++++++++++++++++++++++++++++-------
 src/misc/mtime.c    | 44 ------------------------------
 2 files changed, 68 insertions(+), 53 deletions(-)

diff --git a/include/vlc_mtime.h b/include/vlc_mtime.h
index e387a960e2..ae07f6f126 100644
--- a/include/vlc_mtime.h
+++ b/include/vlc_mtime.h
@@ -56,9 +56,16 @@
  *****************************************************************************/
 VLC_API char * secstotimestr( char *psz_buffer, int32_t secs );
 
-/*****************************************************************************
- * date_t: date incrementation without long-term rounding errors
- *****************************************************************************/
+/**
+ * \defgroup date Timestamps, error-free
+ * These functions support generating timestamps without long term rounding
+ * errors due to sample rate conversions.
+ * \ingroup input
+ * @{
+ */
+/**
+ * Timestamps without long-term rounding errors
+ */
 struct date_t
 {
     mtime_t  date;
@@ -67,11 +74,63 @@ struct date_t
     uint32_t i_remainder;
 };
 
-VLC_API void date_Init( date_t *, uint32_t, uint32_t );
-VLC_API void date_Change( date_t *, uint32_t, uint32_t );
-VLC_API void date_Set( date_t *, mtime_t );
-VLC_API mtime_t date_Get( const date_t * );
-VLC_API mtime_t date_Increment( date_t *, uint32_t );
-VLC_API mtime_t date_Decrement( date_t *, uint32_t );
+/**
+ * Initializes a date_t.
+ *
+ * \param date date to initialize [OUT]
+ * \param num divider (sample rate) numerator
+ * \param den divider (sample rate) denominator
+ */
+VLC_API void date_Init(date_t *restrict date, uint32_t num, uint32_t den);
+
+/**
+ * Changes the rate of a date_t.
+ *
+ * \param date date to change
+ * \param num divider (sample rate) numerator
+ * \param den divider (sample rate) denominator
+ */
+VLC_API void date_Change(date_t *restrict date, uint32_t num, uint32_t den);
+
+/**
+ * Sets the exact timestamp of a date_t.
+ *
+ * \param date date to set the timestamp into
+ * \param value date value
+ */
+VLC_API void date_Set(date_t *restrict date, mtime_t value);
+
+/**
+ * Gets the current timestamp from a date_t.
+ *
+ * \param date date to fetch the timestamp from
+ * \return date value
+ */
+VLC_API mtime_t date_Get(const date_t *restrict date) VLC_USED;
+
+/**
+ * Increments a date.
+ *
+ * Moves the date_t timestamp forward by a given number of samples.
+ *
+ * \param date date to move forward
+ * \param count number of samples
+ * \return timestamp value after incrementing
+ */
+VLC_API mtime_t date_Increment(date_t *restrict date, uint32_t count);
+
+/**
+ * Decrements a date.
+ *
+ * Moves the date_t timestamp backward by a given number of samples.
+ *
+ * \param date date to move backward
+ * \param count number of samples
+ * \return date value
+ */
+VLC_API mtime_t date_Decrement(date_t *restrict date, uint32_t count);
+
+/** @} */
+
 VLC_API uint64_t NTPtime64( void );
 #endif /* !__VLC_MTIME_ */
diff --git a/src/misc/mtime.c b/src/misc/mtime.c
index 4eb60fe92b..ca289d32e4 100644
--- a/src/misc/mtime.c
+++ b/src/misc/mtime.c
@@ -76,14 +76,6 @@ char *secstotimestr( char *psz_buffer, int32_t i_seconds )
  * Date management (internal and external)
  */
 
-/**
- * Initialize a date_t.
- *
- * \param date to initialize
- * \param divider (sample rate) numerator
- * \param divider (sample rate) denominator
- */
-
 void date_Init( date_t *p_date, uint32_t i_divider_n, uint32_t i_divider_d )
 {
     p_date->date = 0;
@@ -92,14 +84,6 @@ void date_Init( date_t *p_date, uint32_t i_divider_n, uint32_t i_divider_d )
     p_date->i_remainder = 0;
 }
 
-/**
- * Change a date_t.
- *
- * \param date to change
- * \param divider (sample rate) numerator
- * \param divider (sample rate) denominator
- */
-
 void date_Change( date_t *p_date, uint32_t i_divider_n, uint32_t i_divider_d )
 {
     /* change time scale of remainder */
@@ -108,37 +92,17 @@ void date_Change( date_t *p_date, uint32_t i_divider_n, uint32_t i_divider_d )
     p_date->i_divider_den = i_divider_d;
 }
 
-/**
- * Set the date value of a date_t.
- *
- * \param date to set
- * \param date value
- */
 void date_Set( date_t *p_date, mtime_t i_new_date )
 {
     p_date->date = i_new_date;
     p_date->i_remainder = 0;
 }
 
-/**
- * Get the date of a date_t
- *
- * \param date to get
- * \return date value
- */
 mtime_t date_Get( const date_t *p_date )
 {
     return p_date->date;
 }
 
-/**
- * Increment the date and return the result, taking into account
- * rounding errors.
- *
- * \param date to increment
- * \param incrementation in number of samples
- * \return date value
- */
 mtime_t date_Increment( date_t *p_date, uint32_t i_nb_samples )
 {
     assert( p_date->i_divider_num != 0 );
@@ -159,14 +123,6 @@ mtime_t date_Increment( date_t *p_date, uint32_t i_nb_samples )
     return p_date->date;
 }
 
-/**
- * Decrement the date and return the result, taking into account
- * rounding errors.
- *
- * \param date to decrement
- * \param decrementation in number of samples
- * \return date value
- */
 mtime_t date_Decrement( date_t *p_date, uint32_t i_nb_samples )
 {
     mtime_t i_dividend = (mtime_t)i_nb_samples * CLOCK_FREQ * p_date->i_divider_den;