> 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
http://www.doxygen.nl/.
Regards,
John Ralls
_______________________________________________
gnucash-devel mailing list
gnucash-devel@gnucash.org
https://lists.gnucash.org/mailman/listinfo/gnucash-devel