On 04/29/2012 11:48 AM, Lorenzo Marcantonio wrote: > On Sun, Apr 29, 2012 at 06:05:36PM +0200, Lorenzo Marcantonio wrote: >> OK. Didn't knew about the doxygen bit. > I pondered about the doxygen policy... having the full docs inside the header > and not in the source file is awfully inconvenient...
Not so much for me: $ make doxygen-docs $ firefox ../Documentation/doxygen/html/index.html Use the browser to study code you are not familiar with. > > I usually do something like this: > - The header is mostly plain with member divided in section (to find stuff > quickly) > - The implementation contains the full doc... for overridden virtual function > I simply > notice the difference against the parent implementation. Of course pures > and inlines > are commented in the headers... > > The same doxygen manual says: > > Unlike most other documentation systems, doxygen also allows you to put the > documentation of members (including global functions) in front of the > definition. This way the documentation can be placed in the source file > instead of the header file. This keeps the header file compact, and allows > the implementer of the members more direct access to the documentation. As > a > compromise the brief description could be placed before the declaration and > the detailed description before the member definition I was quite certain what my preference was when I wrote this section of the coding standards. I won't yield, Wayne and I have too much into this already. It was partially a comment maintenance reduction choice, and ambiguity reduction. > > BTW I find the 'missing' header file a big nuisance in java! No two people agree on everything. _______________________________________________ Mailing list: https://launchpad.net/~kicad-developers Post to : [email protected] Unsubscribe : https://launchpad.net/~kicad-developers More help : https://help.launchpad.net/ListHelp
