incubator-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 19:22:24 GMT
 

> -----Original Message-----
> From: Martin Sebor [mailto:sebor@roguewave.com] 
> Sent: Monday, June 23, 2008 11:38 AM
> To: dev@stdcxx.apache.org
> Subject: Re: svn commit: r667636 - 
> /stdcxx/branches/4.3.x/include/rw/_forward.h
> 
> 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

What Travis said: if we don't write it ourselves, it probably won't
get written.  :)  I also agree: I'd rather write doc comments than
update the existing raw HTML docs.

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

That's subjective.  Because they are more structured than free-form
comments, I find them easier to read.

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

I consider that icing on the cake.  You can still generate docs
without having them published online.

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

This can be controlled with conditional sections and comments, using
@if tags, @internal tags, _RWSTD_EXT_DOXYGEN macro, and other such
mechanisms.

Brad.

Mime
View raw message