> -----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. I believe Travis did some quick performance tests to verify these empirical conclusions. Brad.
