rational: Extend Doxygen

libavutil/rational.h

@@ -21,7 +21,8 @@
 
 /**
  * @file
- * rational numbers
+ * @ingroup lavu_math_rational
+ * Utilties for rational number calculation.
  * @author Michael Niedermayer <michaelni@gmx.at>
  */
 
@@ -33,22 +34,39 @@
 #include "attributes.h"
 
 /**
- * @addtogroup lavu_math
+ * @defgroup lavu_math_rational AVRational
+ * @ingroup lavu_math
+ * Rational number calculation.
+ *
+ * While rational numbers can be expressed as floating-point numbers, the
+ * conversion process is a lossy one, so are floating-point operations. On the
+ * other hand, the nature of FFmpeg demands highly accurate calculation of
+ * timestamps. This set of rational number utilities serves as a generic
+ * interface for manipulating rational numbers as pairs of numerators and
+ * denominators.
+ *
+ * Many of the functions that operate on AVRational's have the suffix `_q`, in
+ * reference to the mathematical symbol "ℚ" (Q) which denotes the set of all
+ * rational numbers.
+ *
  * @{
  */
 
 /**
- * rational number numerator/denominator
+ * Rational number (pair of numerator and denominator).
  */
 typedef struct AVRational{
-    int num; ///< numerator
+    int num; ///< Numerator
-    int den; ///< denominator
+    int den; ///< Denominator
 } AVRational;
 
 /**
- * Create a rational.
+ * Create an AVRational.
+ *
  * Useful for compilers that do not support compound literals.
- * @note  The return value is not reduced.
+ *
+ * @note The return value is not reduced.
+ * @see av_reduce()
  */
 static inline AVRational av_make_q(int num, int den)
 {
@@ -58,10 +76,15 @@ static inline AVRational av_make_q(int num, int den)
 
 /**
  * Compare two rationals.
- * @param a first rational
+ *
- * @param b second rational
+ * @param a First rational
- * @return 0 if a==b, 1 if a>b, -1 if a<b, and INT_MIN if one of the
+ * @param b Second rational
- * values is of the form 0/0
+ *
+ * @return One of the following values:
+ *         - 0 if `a == b`
+ *         - 1 if `a > b`
+ *         - -1 if `a < b`
+ *         - `INT_MIN` if one of the values is of the form `0 / 0`
  */
 static inline int av_cmp_q(AVRational a, AVRational b){
     const int64_t tmp= a.num * (int64_t)b.den - b.num * (int64_t)a.den;
@@ -73,9 +96,10 @@ static inline int av_cmp_q(AVRational a, AVRational b){
 }
 
 /**
- * Convert rational to double.
+ * Convert an AVRational to a `double`.
- * @param a rational to convert
+ * @param a AVRational to convert
- * @return (double) a
+ * @return `a` in floating-point form
+ * @see av_d2q()
  */
 static inline double av_q2d(AVRational a){
     return a.num / (double) a.den;
@@ -83,44 +107,46 @@ static inline double av_q2d(AVRational a){
 
 /**
  * Reduce a fraction.
+ *
  * This is useful for framerate calculations.
- * @param dst_num destination numerator
+ *
- * @param dst_den destination denominator
+ * @param[out] dst_num Destination numerator
- * @param num source numerator
+ * @param[out] dst_den Destination denominator
- * @param den source denominator
+ * @param[in]      num Source numerator
- * @param max the maximum allowed for dst_num & dst_den
+ * @param[in]      den Source denominator
- * @return 1 if exact, 0 otherwise
+ * @param[in]      max Maximum allowed values for `dst_num` & `dst_den`
+ * @return 1 if the operation is exact, 0 otherwise
  */
 int av_reduce(int *dst_num, int *dst_den, int64_t num, int64_t den, int64_t max);
 
 /**
  * Multiply two rationals.
- * @param b first rational
+ * @param b First rational
- * @param c second rational
+ * @param c Second rational
  * @return b*c
  */
 AVRational av_mul_q(AVRational b, AVRational c) av_const;
 
 /**
  * Divide one rational by another.
- * @param b first rational
+ * @param b First rational
- * @param c second rational
+ * @param c Second rational
  * @return b/c
  */
 AVRational av_div_q(AVRational b, AVRational c) av_const;
 
 /**
  * Add two rationals.
- * @param b first rational
+ * @param b First rational
- * @param c second rational
+ * @param c Second rational
  * @return b+c
  */
 AVRational av_add_q(AVRational b, AVRational c) av_const;
 
 /**
  * Subtract one rational from another.
- * @param b first rational
+ * @param b First rational
- * @param c second rational
+ * @param c Second rational
  * @return b-c
  */
 AVRational av_sub_q(AVRational b, AVRational c) av_const;
@@ -138,31 +164,46 @@ static av_always_inline AVRational av_inv_q(AVRational q)
 
 /**
  * Convert a double precision floating point number to a rational.
- * inf is expressed as {1,0} or {-1,0} depending on the sign.
  *
- * @param d double to convert
+ * In case of infinity, the returned value is expressed as `{1, 0}` or
- * @param max the maximum allowed numerator and denominator
+ * `{-1, 0}` depending on the sign.
- * @return (AVRational) d
+ *
+ * @param d   `double` to convert
+ * @param max Maximum allowed numerator and denominator
+ * @return `d` in AVRational form
+ * @see av_q2d()
  */
 AVRational av_d2q(double d, int max) av_const;
 
 /**
- * @return 1 if q1 is nearer to q than q2, -1 if q2 is nearer
+ * Find which of the two rationals is closer to another rational.
- * than q1, 0 if they have the same distance.
+ *
+ * @param q     Rational to be compared against
+ * @param q1,q2 Rationals to be tested
+ * @return One of the following values:
+ *         - 1 if `q1` is nearer to `q` than `q2`
+ *         - -1 if `q2` is nearer to `q` than `q1`
+ *         - 0 if they have the same distance
  */
 int av_nearer_q(AVRational q, AVRational q1, AVRational q2);
 
 /**
- * Find the nearest value in q_list to q.
+ * Find the value in a list of rationals nearest a given reference rational.
- * @param q_list an array of rationals terminated by {0, 0}
+ *
- * @return the index of the nearest value found in the array
+ * @param q      Reference rational
+ * @param q_list Array of rationals terminated by `{0, 0}`
+ * @return Index of the nearest value found in the array
  */
 int av_find_nearest_q_idx(AVRational q, const AVRational* q_list);
 
 /**
- * Converts a AVRational to a IEEE 32bit float.
+ * Convert an AVRational to a IEEE 32-bit `float` expressed in fixed-point
+ * format.
  *
- * The float is returned in a uint32_t and its value is platform indepenant.
+ * @param q Rational to be converted
+ * @return Equivalent floating-point value, expressed as an unsigned 32-bit
+ *         integer.
+ * @note The returned value is platform-indepedant.
  */
 uint32_t av_q2intfloat(AVRational q);