kicad-developers team mailing list archive

[Dick Hollenbeck <dick@xxxxxxxxxxx>]

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.