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