> -----Original Message----- > From: Martin Sebor [mailto:[EMAIL PROTECTED] > 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:[EMAIL PROTECTED] > >> 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.
