From dev-return-7920-apmail-stdcxx-dev-archive=stdcxx.apache.org@stdcxx.apache.org Mon Jun 23 17:38:07 2008 Return-Path: Delivered-To: apmail-stdcxx-dev-archive@www.apache.org Received: (qmail 20147 invoked from network); 23 Jun 2008 17:38:07 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 23 Jun 2008 17:38:07 -0000 Received: (qmail 35959 invoked by uid 500); 23 Jun 2008 17:38:09 -0000 Delivered-To: apmail-stdcxx-dev-archive@stdcxx.apache.org Received: (qmail 35942 invoked by uid 500); 23 Jun 2008 17:38:09 -0000 Mailing-List: contact dev-help@stdcxx.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@stdcxx.apache.org Delivered-To: mailing list dev@stdcxx.apache.org Received: (qmail 35921 invoked by uid 99); 23 Jun 2008 17:38:09 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 23 Jun 2008 10:38:09 -0700 X-ASF-Spam-Status: No, hits=-0.0 required=10.0 tests=SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (athena.apache.org: local policy) Received: from [208.30.140.160] (HELO moroha.roguewave.com) (208.30.140.160) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 23 Jun 2008 17:37:19 +0000 Received: from nebula.bco.roguewave.com ([10.70.3.27]) by moroha.roguewave.com (8.13.6/8.13.6) with ESMTP id m5NHbces020845 for ; Mon, 23 Jun 2008 17:37:38 GMT Message-ID: <485FDF62.6040606@roguewave.com> Date: Mon, 23 Jun 2008 11:37:38 -0600 From: Martin Sebor Organization: Rogue Wave Software, Inc. User-Agent: Thunderbird 2.0.0.12 (X11/20080226) MIME-Version: 1.0 To: dev@stdcxx.apache.org Subject: Re: svn commit: r667636 - /stdcxx/branches/4.3.x/include/rw/_forward.h References: <20080613201606.7C7512388A0A@eris.apache.org> <485FBEA3.2020402@roguewave.com> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Virus-Checked: Checked by ClamAV on apache.org 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 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 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 4) the HTML generated from stdcxx headers is unavoidably ugly because of the necessity to uglify names (leading underscores, etc.) Martin