kicad-developers team mailing list archive

[jean-pierre charras - INPG <jean-pierre.charras@...>]

Wayne Stambaugh a écrit :
> 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
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