From 3c860737f1a74289513420d2393f9d84f6e9624b Mon Sep 17 00:00:00 2001 From: Geert Janssens Date: Sat, 18 May 2024 17:20:15 +0200 Subject: [PATCH] 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 | 1 - libgnucash/doc/doxygen_main_page.c | 1 - libgnucash/engine/CMakeLists.txt | 1 + .../TaxTableBillTermImmutability.txt} | 48 ++----------------- libgnucash/engine/gncAddress.h | 37 +++++++------- libgnucash/engine/gncBillTerm.c | 2 +- libgnucash/engine/gncBillTerm.h | 39 ++++++++++++++- libgnucash/engine/gncBusiness.h | 3 +- libgnucash/engine/gncTaxTable.c | 4 +- libgnucash/engine/gncTaxTable.h | 2 +- 10 files changed, 68 insertions(+), 70 deletions(-) rename libgnucash/{doc/business.txt => engine/TaxTableBillTermImmutability.txt} (55%) diff --git a/libgnucash/doc/CMakeLists.txt b/libgnucash/doc/CMakeLists.txt index 3951484b85..dc33c60103 100644 --- a/libgnucash/doc/CMakeLists.txt +++ b/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 diff --git a/libgnucash/doc/doxygen_main_page.c b/libgnucash/doc/doxygen_main_page.c index 0d944760a4..d50603987e 100644 --- a/libgnucash/doc/doxygen_main_page.c +++ b/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 diff --git a/libgnucash/engine/CMakeLists.txt b/libgnucash/engine/CMakeLists.txt index dd9f63fb7c..3a5c3e4c4a 100644 --- a/libgnucash/engine/CMakeLists.txt +++ b/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) diff --git a/libgnucash/doc/business.txt b/libgnucash/engine/TaxTableBillTermImmutability.txt similarity index 55% rename from libgnucash/doc/business.txt rename to libgnucash/engine/TaxTableBillTermImmutability.txt index badd8521ad..0f55993028 100644 --- a/libgnucash/doc/business.txt +++ b/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 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 ------------------------------ diff --git a/libgnucash/engine/gncAddress.h b/libgnucash/engine/gncAddress.h index 34db15eeb9..09421f9be5 100644 --- a/libgnucash/engine/gncAddress.h +++ b/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 diff --git a/libgnucash/engine/gncBillTerm.c b/libgnucash/engine/gncBillTerm.c index 604786a4fa..9be71330dc 100644 --- a/libgnucash/engine/gncBillTerm.c +++ b/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 */ diff --git a/libgnucash/engine/gncBillTerm.h b/libgnucash/engine/gncBillTerm.h index ce8621ee9d..8c44e1b8ab 100644 --- a/libgnucash/engine/gncBillTerm.h +++ b/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 diff --git a/libgnucash/engine/gncBusiness.h b/libgnucash/engine/gncBusiness.h index ecdd785fb4..aef11b0b33 100644 --- a/libgnucash/engine/gncBusiness.h +++ b/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 diff --git a/libgnucash/engine/gncTaxTable.c b/libgnucash/engine/gncTaxTable.c index 9ffd37720b..fec75d7aed 100644 --- a/libgnucash/engine/gncTaxTable.c +++ b/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 */ diff --git a/libgnucash/engine/gncTaxTable.h b/libgnucash/engine/gncTaxTable.h index d6b167e02f..4b0fe0affb 100644 --- a/libgnucash/engine/gncTaxTable.h +++ b/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