kicad-developers team mailing list archive
Mailing list archive
Re: Doxygen comments.
Dick Hollenbeck <dick@...>
Wed, 07 Oct 2009 09:34:37 -0500
Thunderbird 22.214.171.124 (X11/20090817)
Wayne Stambaugh wrote:
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.
In my opinion they should be ONLY in the header files, simply because I
do not like to MAINTAIN two copies. For me it is about maintenance
simplicity. I would rather have to go to the header file than have two
dis-agreeing copies, one in the header and one in the source file, or to
have to burden of keeping them in sync. All the code I have written in
the project conforms to this.
In this regard, Java is a step forward over C++ : no header files. So
in that case, the comments can go right with the code.
Java is pretty nice for application development.