r19251 - gnucash/trunk/src/business/business-core - Explain proximo concept.

[Geert Janssens]

Author: gjanssens
Date: 2010-06-12 09:00:30 -0400 (Sat, 12 Jun 2010)
New Revision: 19251
Trac: http://svn.gnucash.org/trac/changeset/19251

Modified:
   gnucash/trunk/src/business/business-core/gncBillTerm.c
Log:
Explain proximo concept.

Modified: gnucash/trunk/src/business/business-core/gncBillTerm.c
===================================================================
--- gnucash/trunk/src/business/business-core/gncBillTerm.c	2010-06-12 09:23:51 UTC (rev 19250)
+++ gnucash/trunk/src/business/business-core/gncBillTerm.c	2010-06-12 13:00:30 UTC (rev 19251)
@@ -768,9 +768,30 @@
 
 #define SECS_PER_DAY 86400
 
-/* Based on the timespec and a proximo type, compute the month and
+/* Based on the post date and a proximo type, compute the month and
  * year this is due.  The actual day is filled in below.
- * XXX explain this, the logic is totally opaque to me.
+ *
+ * A proximo billing term has multiple parameters:
+ * * due day: day of the month the invoice/bill will be due
+ * * cutoff: day of the month used to decide if the due date will be
+ *           in the next month or in the month thereafter. This can be
+ *           a negative number in which case the cutoff date is relative
+ *           to the end of the month and counting backwards.
+ *           Eg: cutoff = -3 would mean 25 in February or 28 in June
+ *
+ * How does it work:
+ * Assume cutoff = 19 and due day = 20
+ *
+ * * Example 1 post date = 14-06-2010 (European date format)
+ *   14 is less than the cutoff of 19, so the due date will be in the next
+ *   month. Since the due day is set to 20, the due date will be
+ *   20-07-2010
+ *
+ * * Example 2 post date = 22-06-2010 (European date format)
+ *   22 is more than the cutoff of 19, so the due date will be in the month
+ *   after next month. Since the due day is set to 20, the due date will be
+ *   20-02-2010
+ *
  */
 static void
 compute_monthyear (const GncBillTerm *term, Timespec post_date,
@@ -807,7 +828,16 @@
     if (year) *year = iyear;
 }
 
-/* XXX explain this, the logic is totally opaque to me. */
+/* There are two types of billing terms:
+ *
+ * Type DAYS defines a due date to be a fixed number of days passed the post
+ * date. This is a straightforward calculation.
+ *
+ * The other type PROXIMO defines the due date as a fixed day of the month
+ * (like always the 15th of the month). The proximo algorithm determines which
+ * month based on the cutoff day and the post date. See above for a more
+ * detailed explanation of proximo.
+ */
 
 static Timespec
 compute_time (const GncBillTerm *term, Timespec post_date, int days)