kicad-developers team mailing list archive

[Wayne Stambaugh <stambaughw@...>]

jean-pierre charras - INPG wrote:
> 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.

Sorry about that. When I looked at the SVN log, I missed that it was
still in the header. It does seem a bit redundant to have the same
comments in two places though.

> 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.

It's not a problem. I just ran Doxygen on the Kicad source and I didn't
notice any duplication of the comments.

Wayne

> If yes, i'll change comments i wrote in .cpp files in order to make them 
> not visible by Doxygen.
>