stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Eric Lemings" <Eric.Lemi...@roguewave.com>
Subject RE: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h
Date Mon, 23 Jun 2008 17:08:06 GMT
 

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

I believe Travis did some quick performance tests to verify these
empirical conclusions.

Brad.

Mime
View raw message