r20753 - gnucash/trunk/src/libqof/qof - Add some more doxygen comments for gnc_numeric.

Christian Stimming cstim at code.gnucash.org
Sun Jun 12 15:29:08 EDT 2011


Author: cstim
Date: 2011-06-12 15:29:07 -0400 (Sun, 12 Jun 2011)
New Revision: 20753
Trac: http://svn.gnucash.org/trac/changeset/20753

Modified:
   gnucash/trunk/src/libqof/qof/gnc-numeric.h
Log:
Add some more doxygen comments for gnc_numeric.

Modified: gnucash/trunk/src/libqof/qof/gnc-numeric.h
===================================================================
--- gnucash/trunk/src/libqof/qof/gnc-numeric.h	2011-06-11 19:26:56 UTC (rev 20752)
+++ gnucash/trunk/src/libqof/qof/gnc-numeric.h	2011-06-12 19:29:07 UTC (rev 20753)
@@ -73,6 +73,10 @@
     allows the results of financial and other rational computations to be
     properly rounded to the appropriate units.
 
+    Watch out: You \e must specifiy a rounding policy such as
+    GNC_HOW_RND_NEVER, otherwise the fractional part of the input
+    value might silently get discarded!
+
     Valid values for denom are:
     GNC_DENOM_AUTO  -- compute denominator exactly
     integer n       -- Force the denominator of the result to be this integer
@@ -127,6 +131,10 @@
  *  "3/4" but the specified denominator for the return value is 2, should
  *  the return value be "1/2" or "2/2"?
  *
+ * Watch out: You \e must specifiy a rounding policy such as
+ * GNC_HOW_RND_NEVER, otherwise the fractional part of the input value
+ * might silently get discarded!
+ *
  * Possible rounding instructions are:
  */
 enum
@@ -241,7 +249,8 @@
 /** @name Constructors
 @{
 */
-/** Make a gnc_numeric from numerator and denominator */
+/** Returns a newly created gnc_numeric with the given numerator and
+ * denominator, that is "num/denom". */
 static inline
 gnc_numeric gnc_numeric_create(gint64 num, gint64 denom)
 {
@@ -251,7 +260,7 @@
     return out;
 }
 
-/** create a zero-value gnc_numeric */
+/** Returns a newly created gnc_numeric of value zero, that is "0/1". */
 static inline
 gnc_numeric gnc_numeric_zero(void)
 {
@@ -259,9 +268,28 @@
 }
 
 /** Convert a floating-point number to a gnc_numeric.
- *  Both 'denom' and 'how' are used as in arithmetic,
- *  but GNC_DENOM_AUTO is not recognized; a denominator
- *  must be specified either explicitctly or through sigfigs.
+ *
+ * Both 'denom' and 'how' are used as in arithmetic, but
+ * GNC_DENOM_AUTO is not recognized; a denominator must be specified
+ * either explicitly or through sigfigs.
+ *
+ * \sa \ref Arguments
+ *
+ * \param n The double value that is converted into a gnc_numeric
+ *
+ * \param denom The denominator of the gnc_numeric return value. If
+ * the 'how' argument contains the GNC_HOW_DENOM_SIGFIG flag, this
+ * value will be ignored.
+ *
+ * \param how Describes the rounding policy and output
+ * denominator. Watch out: You \e must specifiy a rounding policy such
+ * as GNC_HOW_RND_NEVER, otherwise the fractional part of the input
+ * value is silently discarded! Common values for 'how' are
+ * (GNC_HOW_DENOM_REDUCE|GNC_HOW_RND_NEVER) or
+ * (GNC_HOW_DENOM_FIXED|GNC_HOW_RND_NEVER). As mentioned above,
+ * GNC_DENOM_AUTO is not allowed here.
+ *
+ * \return The newly created gnc_numeric rational value.
  */
 gnc_numeric double_to_gnc_numeric(double n, gint64 denom,
                                   gint how);
@@ -284,13 +312,13 @@
 /** @name Value Accessors
  @{
 */
-/** Return numerator */
+/** Returns the numerator of the given gnc_numeric value. */
 static inline
 gint64 gnc_numeric_num(gnc_numeric a)
 {
     return a.num;
 }
-/** Return denominator */
+/** Returns the denominator of the given gnc_numeric value. */
 static inline
 gint64 gnc_numeric_denom(gnc_numeric a)
 {
@@ -385,10 +413,14 @@
  */
 gnc_numeric gnc_numeric_div(gnc_numeric x, gnc_numeric y,
                             gint64 denom, gint how);
-/** Negate the argument  */
+/** Returns a newly created gnc_numeric that is the negative of the
+ * given gnc_numeric value. For a given gnc_numeric "a/b" the returned
+ * value is "-a/b".  */
 gnc_numeric gnc_numeric_neg(gnc_numeric a);
 
-/** Return the absolute value of the argument */
+/** Returns a newly created gnc_numeric that is the absolute value of
+ * the given gnc_numeric value. For a given gnc_numeric "a/b" the
+ * returned value is "|a/b|". */
 gnc_numeric gnc_numeric_abs(gnc_numeric a);
 
 /**



More information about the gnucash-changes mailing list