> On Aug 13, 2019, at 6:25 PM, David Cousens <davidcous...@bigpond.com> wrote:
> At present the transaction importing documentation in the Help manual has no
> full description of how the import main matcher goes about the process of
> searching for and matching an imported transaction to an existing
> transaction or how it assigns a transfer account using the original mapping
> process or the more recent Bayesian approach. 
> I am in the process of going through the code at present for my own
> edification and could create an expanded description of these processes in
> their current state either for inclusion in the Help manual or  as a Wiki
> page. My concern is that a detailed explanantion in the importing
> transaction section of the help manual may make that section too long
> winded. If that is not a significant issue, that would be my personal
> preference.
> Does anyone have any strong preferences as to which is the better option ?

I'd rather not document internals in the T&CG. Implementation details aren't 
something that users need to worry about, so document there what it does, but 
not how. 

How belongs in comments in the code. Exported functions should have 
Doxygen-formatted comments so that they add to the API documentation 
(https://code.gnucash.org/docs/MAINT), local functions may also have 
non-Doxygen comments. Beware that a lot of our code follows the Gnome dispatch 
model where a static function is exported via a hand-written vtable, usually 
placed near the bottom of the source file. Those functions are really public 
and rate Doxygen documentation.

Bigger-picture documentation of a module's design also belongs in 
Doxygen-formatted comments. If you're not familiar with Doxygen see 

John Ralls

gnucash-devel mailing list

Reply via email to