stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Martin Sebor <se...@roguewave.com>
Subject Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Date Mon, 23 Jun 2008 17:37:38 GMT
Eric Lemings wrote:
>  
> 
>> -----Original Message-----
>> From: Travis Vitek [mailto:Travis.Vitek@roguewave.com] 
>> Sent: Monday, June 23, 2008 10:13 AM
>> To: dev@stdcxx.apache.org
>> Subject: RE: svn commit: r667636 - 
>> /stdcxx/branches/4.3.x/include/rw/_forward.h
>>
>>  
>>
>> Martin Sebor wrote:
>>> Eric Lemings wrote:
>>>>  
>>>> Gah.  I have to update my docs as well: template parameters are
>>>> documented using the @tparam tag rather than the @param tag.
>>> I thought we said we wouldn't be using doxygen comments in
>>> library code. Am I misremembering?
>>>
>> I know that it was requested that I remove the doxygen 
>> comments from the
>> type traits stuff I have been working on, but I decided it 
>> would be best
>> to commit them with the comments intact and remove them only if
>> necessary. I mentioned this to Brad in our off-list 
>> correspondence, and
>> he has opted to do the same.
>>
>> As I sit here thinking about it, I can't remember exactly why it was
>> decided that they should be removed. Perhaps it is best to have this
>> discussion again, but on the list this time.
>>
>> To start, I'm not sure I understand the motivation for _not_ using
>> doxygen in the library headers. I realize that having documentation in
>> the code is a departure from what stdcxx has done in the past, but I'm
>> not convinced that this is a bad thing.
> 
> I'll add a couple points to that for the record.
> 
> Much of this was precipitated when I noticed that GNU libstdc++ also
> includes their documentation right in the library headers and source
> code.  Why?  Because most, if not all, C/C++ preprocessors will strip
> comments by default during a first pass.  Thus, the impact of extensive
> documentation comments on overall build times is negligible.

Of course preprocessors strip comments. It's required by
the language standards. But regardless of the translation
stage at which the stripping takes place, it isn't without
cost.

I gave a number of arguments against Doxygen comments in
stdcxx headers:

1)  existing code doesn't use it and converting the raw HTML
     docs to Doxygen is an enormous task that none of us has
     the time to take on; Doxygenating new code without doing
     the same for the existing code is inconsistent and won't
     help us produce end-user documentation for the finished
     product

2)  Doxygen markups are harder to read than ordinary comments
     (see 3), and in the library headers the volume of such
     comments will, in many cases, dwarf the amount of code

3)  unless/until there is infrastructure to generate the HTML
     docs from the Doxygen comments documenting the library (or
     other parts of stdcxx) using Doxygen markups serves no
     purpose

4)  the HTML generated from stdcxx headers is unavoidably
     ugly because of the necessity to uglify names (leading
     underscores, etc.)

Martin

Mime
View raw message