← Back to team overview

kicad-developers team mailing list archive

Re: Doxygen comments.


Wayne Stambaugh a écrit :


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.


The comments are always in headers files!
( LIB_COMPONENT: :LocateDrawItem( ) is commented in the header file, i did not move it) I just duplicated them when i added the overlaid LocateDrawItem. in the .cpp files.

No need to change coding standards.
These comments are in good place in headers (and most of developers expect these comments in headers).

Just, many times I duplicate them in the .cpp file because it is easier (to me) to have these comments in both files, when i write functions.
(I put them always in headers).
Of course, old headers do not have these comments, but for now, i put these comments are in .h files and a copy of them in .cpp files.

I do not know if duplicate comments (in headers and .cpp files) are a problem for Doxygen. If yes, i'll change comments i wrote in .cpp files in order to make them not visible by Doxygen.

Jean-Pierre CHARRAS
Maître de conférences
Directeur d'études 2ieme année.
Génie Electrique et Informatique Industrielle 2
Institut Universitaire de Technologie 1 de Grenoble
BP 67, 38402 St Martin d'Heres Cedex

Recherche :
Grenoble Image Parole Signal Automatique (GIPSA - INPG)
Grenoble France

Follow ups