kicad-developers team mailing list archive

[Isaac Marino Bavaresco <isaacbavaresco@...>]

Wayne Stambaugh escreveu:
> 
>
> JP,
>
> I noticed that you moved the comments I wrote for
> LIB_COMPONENT::LocateDrawItem() from the header file to the source file.
> This comment was formatted for Doxygen to generate source code
> documentation files. Generally speaking, these comments are placed in
> the header file ( see the header files in the wxWidgets source for some
> very good examples ). Doxygen will correctly parse these comments
> whether they are in the header or the source file. In the Kicad source,
> there is no consistency to where Doxygen comments are placed. In some
> cases the same comment is in both the header and the source file. I
> personally prefer them in the header file ( mainly because emacs will
> syntax highlight them when they are in the header ) but more importantly
> I prefer that they be consistent so I know where to look for them. I
> know we currently don't generate source documentation with Doxygen but
> it would be nice to get the code base to the point where we could to
> help out developers. Anyone one else have any thoughts on this? Maybe
> its time to take another look at writing some coding standards.
>
> Wayne
>
I agree that defining a coding standard is a good thing. With so many
developers and no style guidelines, the code becomes too discontinuous.

About Doxygen, it can extract documentation even without or with little
special comments if you activate the "EXTRACT_ALL" switch.

It is very useful and I already processed the Kicad´s code with Doxygen.
It is very useful to to be able to read the classes relationships in a
web-browser.

If you create the documenting comments in the header files, you may
process only the header files and get all the interface details, with
the implementation details hidden. I would say it is a good thing for a
library, where you want just to use its functions and don´t want to
bother with its internals, less useful for an application where you are
going to change the code. But it is better to document in the header
files anyway.

Best regards,

Isaac

__________________________________________________
Faça ligações para outros computadores com o novo Yahoo! Messenger 
http://br.beta.messenger.yahoo.com/