Doxygen - fold business.txt file in the respective source files

The file mostly had short descriptions that were very similar
to the descriptions of business objects it referred to. The
exception was an explanation of how the billing terms and
tax tables handled their immutable copies. That bit has been
moved to its own group under the Business group and is referenced
from the BillTerm and TaxTables group.

This commit also fixes rendering of the Address doxygen info
and expands the BillTerm info to explain how proximo due dates
work.

libgnucash/doc/CMakeLists.txt

@@ -7,7 +7,6 @@ set(doc_FILES
         backup.txt
         books.txt
         budget.txt
-#        business.txt
         callgrind.txt
         constderv.html
 #        constraints.txt

libgnucash/doc/doxygen_main_page.c

@@ -32,7 +32,6 @@ in relation to existing code.
 
 - \ref backuppolicy
 - \ref bookperiods
-- \ref business1
 - \ref currencies
 - \ref deprecated
 - \ref engine

libgnucash/engine/CMakeLists.txt

@@ -284,6 +284,7 @@ set(engine_EXTRA_DIST
         README
         README.query-api
         SX-book-p.h
+        TaxTableBillTermImmutability.txt
         )
 
 if (NOT WIN32)

libgnucash/engine/TaxTableBillTermImmutability.txt

@@ -1,45 +1,7 @@
-/** \page business1 Business Overview
-
-API: \ref Business
-
-\section businessoverview Business Objects
-
-The GnuCash Business objects, in src/business/business-core, implement
-certain basic small-business accounting functions.  Below follows a summary
-overview of the objects and the data that they store.  These are listed in
-order of complexity; with the basic building blocks first, and the more 
-complex structures last.
-
-\subsection address Address:
-A very simple object, stores strings for name/street-address/phone/fax/email
-The address is not a separate entity, but is meant to be embedded in other 
-objects (that is, there is no addressbook; there is no address database that
-is separate from the objects that use addresses; there is no 'foreach'
-that can be used to iterate over all addresses.)
-
-API: \ref Address
-
-\subsection billterm BillTerm:
-Describes billing terms, that is when a bill is due, and what sort of a 
-discount is applied (if any).  The BillTerm object currently supports:
--- the discount applied to a bill (absolute numeric value),
--- the number of days until payment is due, 
--- the number of days until a discount expires.
--- cutoff ??
-The proximo type does what ???
-
-API: \ref BillTerm
-
-\subsection entry Entry:
-
-\subsection invoice Invoice:
-Pulls together info needed to generate an invoice, including addresses,
-job, the dates, the billing terms, the amounts, and the accounts
-to be credited.
-
-API: \ref Entry
-
-\section bus_design Business Design & Implementation Notes
+/**
+ \addtogroup Business
+ @{
+    \addtogroup ImmutableTaxTableBillTerm TaxTable and BillTerm immutability tracking
 
 Derek Atkins <warlord@mit.edu>
 Version of October 2003
@@ -77,5 +39,3 @@ explanation:
 - A parent has a pointer to the current 'replica child', if one exists.
 
 */
-
-------------------------- end of file ------------------------------

libgnucash/engine/gncAddress.h

@@ -22,27 +22,30 @@
 /** @addtogroup Business
     @{ */
 /** @addtogroup Address
+    An address is a helper object used by the ::GncOwner object (and
+    its actual implementations ::GncCustomer, ::GncVendor and ::GncEmployee).
 
-An address belongs to another object, determined by the ::GncOwner.
-It is the owner that assigns a name and identifier to the address.
-In effect, an address is just a building - to make it useful to
-GnuCash, it needs to be tied to a person. After all, you cannot
-invoice a building, you invoice a person working / living in the
-building.
+    An address stores the physical address, phone, fax and email properties
+    of a ::GncOwner. The owner's name itself is stored in ::GncOwner.
 
-QOF needs to handle all objects generically and to tie the address
-to an owner, QOF must be able to find each - as entities.
+    @note an address is not a separate entity. It is meant to be embedded in other
+    objects (that is, there is no addressbook; there is no address database that
+    is separate from the objects that use addresses; there is no 'foreach'
+    that can be used to iterate over all addresses.)
 
-This allows QOF to follow the hierarchy of objects without having
-to call any application-specific routines.
+    QOF needs to handle all objects generically and to tie the address
+    to an owner, QOF must be able to find each - as entities.
 
-To achieve this, new GncAddress routines have been added. An address
-is now created with a NULL parent and the parent set explicitly using
-the QOF object declaration. Whilst this adds functionality, it is
-important that a valid ::GncOwner entity is always set as a parent.
-This is an API issue - QOF will always set the parent provided that
-a suitable entity is passed to the qofAddressSetOwner routine. It is
-up to you to pass a suitable entity.
+    This allows QOF to follow the hierarchy of objects without having
+    to call any application-specific routines.
+
+    To achieve this, new GncAddress routines have been added. An address
+    is now created with a NULL parent and the parent set explicitly using
+    the QOF object declaration. Whilst this adds functionality, it is
+    important that a valid ::GncOwner entity is always set as a parent.
+    This is an API issue - QOF will always set the parent provided that
+    a suitable entity is passed to the qofAddressSetOwner routine. It is
+    up to you to pass a suitable entity.
 
     @{ */
 /** @file gncAddress.h

libgnucash/engine/gncBillTerm.c

@@ -48,7 +48,7 @@ struct _gncBillTerm
     gint            cutoff;
 
     /* Internal management fields */
-    /* See src/doc/business.txt for an explanation of the following */
+    /* See libgnucash/engine/TaxTableBillTermImmutability.txt for an explanation of the following */
     /* Code that handles this is *identical* to that in gncTaxTable */
     gint64          refcount;
     GncBillTerm *   parent;      /* if non-null, we are an immutable child */

libgnucash/engine/gncBillTerm.h

@@ -21,7 +21,44 @@
 \********************************************************************/
 /** @addtogroup Business
     @{ */
-/** @addtogroup BillTerm
+/** @addtogroup BillTerm Billing Terms
+    Describes billing terms, that is when a bill is due, and what sort of
+    discount is applied (if any).  The BillTerm object currently supports:
+    * the discount applied to a bill (absolute numeric value)
+    * the number of days until a discount expires
+    * information about the invoice due date
+
+    This last one can be defined in multiple ways:
+    * using a simple number of days value: the due date is posted date
+      incremented with this number of days
+    * using the "proximo" method which is explained below:
+
+    A proximo billing term has two 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
+
+    @note A billing term added to an invoice is immutable, that is it
+    can't change any more. To achieve that a billing term is copied when
+    added to an invoice. This uses some internal fields to track this which
+    are explained in @ref ImmutableTaxTableBillTerm.
+
     @{ */
 /** @file gncBillTerm.h
     @brief Billing Term interface

libgnucash/engine/gncBusiness.h

@@ -20,8 +20,7 @@
 /** @addtogroup Engine
     @{ */
 /** @addtogroup Business
-    The Business Engine provides a set of structures for
-    that provide small-business accounting features.
+    This module implements a number of basic small-business accounting functions.
     @{ */
 
 /** @file gncBusiness.h -- Business Helper Functions

libgnucash/engine/gncTaxTable.c

@@ -41,7 +41,7 @@ struct _gncTaxTable
     GncTaxTableEntryList*  entries;
     time64          modtime;      /* internal date of last modtime */
 
-    /* See src/doc/business.txt for an explanation of the following */
+    /* See libgnucash/engine/TaxTableBillTermImmutability.txt for an explanation of the following */
     /* Code that handles this is *identical* to that in gncBillTerm */
     gint64          refcount;
     GncTaxTable *   parent;       /* if non-null, we are an immutable child */
@@ -924,7 +924,7 @@ gboolean gncTaxTableEqual(const GncTaxTable *a, const GncTaxTable *b)
     }
 
 #if 0
-    /* See src/doc/business.txt for an explanation of the following */
+    /* See libgnucash/engine/TaxTableBillTermImmutability.txt for an explanation of the following */
     /* Code that handles this is *identical* to that in gncBillTerm */
     gint64          refcount;
     GncTaxTable *   parent;       /* if non-null, we are an immutable child */

libgnucash/engine/gncTaxTable.h

@@ -38,7 +38,7 @@ extern "C" {
 /** @struct GncTaxTable
 
 modtime is the internal date of the last modtime\n
-See src/doc/business.txt for an explanation of the following\n
+See libgnucash/engine/TaxTableBillTermImmutability.txt for an explanation of the following\n
 Code that handles refcount, parent, child, invisible and children
 is *identical* to that in ::GncBillTerm