Return-Path: 
 <stdcxx-dev-return-123-apmail-incubator-stdcxx-dev-archive=incubator.apache.org@incubator.apache.org>
Delivered-To: apmail-incubator-stdcxx-dev-archive@www.apache.org
Received: (qmail 93856 invoked from network); 7 Sep 2005 10:54:55 -0000
Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199)
  by minotaur.apache.org with SMTP; 7 Sep 2005 10:54:55 -0000
Received: (qmail 65141 invoked by uid 500); 7 Sep 2005 10:54:54 -0000
Delivered-To: apmail-incubator-stdcxx-dev-archive@incubator.apache.org
Received: (qmail 65043 invoked by uid 500); 7 Sep 2005 10:54:54 -0000
Mailing-List: contact stdcxx-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
List-Help: <mailto:stdcxx-dev-help@incubator.apache.org>
List-Unsubscribe: <mailto:stdcxx-dev-unsubscribe@incubator.apache.org>
List-Post: <mailto:stdcxx-dev@incubator.apache.org>
List-Id: <stdcxx-dev.incubator.apache.org>
Reply-To: stdcxx-dev@incubator.apache.org
Delivered-To: mailing list stdcxx-dev@incubator.apache.org
Received: (qmail 64943 invoked by uid 99); 7 Sep 2005 10:54:54 -0000
Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 07 Sep 2005 03:54:53 -0700
X-ASF-Spam-Status: No, hits=0.9 required=10.0
	tests=DNS_FROM_RFC_ABUSE,DNS_FROM_RFC_WHOIS,SPF_HELO_PASS,SPF_PASS
X-Spam-Check-By: apache.org
Received-SPF: pass (asf.osuosl.org: domain of lancediduck@nyc.rr.com
 designates 24.29.109.6 as permitted sender)
Received: from [24.29.109.6] (HELO ms-smtp-02.rdc-nyc.rr.com) (24.29.109.6)
    by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 07 Sep 2005 03:55:05 -0700
Received: from LanceLaptop (cpe-66-65-46-98.nyc.res.rr.com [66.65.46.98])
	by ms-smtp-02.rdc-nyc.rr.com (8.12.10/8.12.7) with ESMTP id j87As1Gg021353;
	Wed, 7 Sep 2005 06:54:22 -0400 (EDT)
Message-Id: <200509071054.j87As1Gg021353@ms-smtp-02.rdc-nyc.rr.com>
From: "Lance Diduck" <lancediduck@nyc.rr.com>
To: <stdcxx-dev@incubator.apache.org>
Cc: "'Martin Sebor'" <sebor@roguewave.com>,
        "'Marc Betz'" <mbetz@roguewave.com>
Subject: RE: stdcxx documentation format
Date: Wed, 7 Sep 2005 06:54:27 -0400
MIME-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: 7bit
X-Mailer: Microsoft Office Outlook, Build 11.0.5510
X-MIMEOLE: Produced By Microsoft MimeOLE V6.00.2900.2180
Thread-index: AcWzkxHKwy4Th/BNRMu/JeWI6BRLzAAA39Iw
In-reply-to: <431EBA73.9020801@alessio.marchetti.name>
X-Virus-Scanned: Symantec AntiVirus Scan Engine
X-Virus-Checked: Checked by ClamAV on apache.org
X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N



Comments on using Doxygen with tr1

1. It is hard to implement a portable tr1, esp type_traits. Making a type
traits that Doxygen understands as well ....
2. Putting the documentation in the code always sounds like a good idea, but
consider that in the STL most of the docs would go in headers, that any
change in headers (including docs) forces a recompilation and a new release
of code, that source headers are already busy with copyright notices,
revision and other coder comments not relevant to a user, porting macros,
and other things.
Using Doxygen to document the test drivers, and generating docs from there I
have found to be a little easier to manage.  
3. Doxygen works best like this:
in foo.h
int foo(int); 
in foo.cpp
/*!
\brief a function called foo
\arg a and integer
\return another integer
\exception std::logic_error int>0

*/
int foo(int a){
	//code
}

However template metaprograms, are almost nothing but declarations. It is
possible to get Doxygen to read this and put in the links, but separating
out the "implementation" (i.e. the detail code) from the "interface' is
solely a job of the documentation. Before choosing Doxygen I would try
documenting a few template metaprograms with it first. I made a small sample
below, and I can give you more if you like.
#if defined( __SUNPRO_CC ) && __SUNPRO_CC<0x550
    #define TYPENAME 
#else
    #define TYPENAME   typename
#endif
namespace tr1{
namespace detail{
   struct is_class_impl {
      template <typename W> static yes_type 
		_m_check(void (W::*)(void) , int);
            template <typename W> static 
             no_type 	_m_check(any_conversion,...);
        }; 
    }//detail

#if !(defined( __SUNPRO_CC )) 
    template<typename tr1_templateargU>  
    struct is_class:integral_constant<bool,
        (sizeof(detail::is_class_impl::_m_check<TYPENAME
remove_cv<tr1_templateargU>::type>(0,0))
        == sizeof(detail::yes_type))> {
    }; 
-- 


-----Original Message-----
From: Alessio Marchetti [mailto:stdcxx@alessio.marchetti.name] 
Sent: Wednesday, September 07, 2005 6:01 AM
To: stdcxx-dev@incubator.apache.org
Cc: Martin Sebor; Marc Betz
Subject: Re: stdcxx documentation format

My comments below...

Alessio


 > There are a couple of projects in use at Apache: Forrest and Maven.
 > I haven't used either but I believe a lot of the Web pages around
 > here are generated by Forrest.

Maven is a PM tool that takes care of automating the build process and the 
project description, but the first goal is met by building upon Ant... and
so it 
is mostly Java-oriented; as far as the second goal, Forrest is a better fit.


 > Going the Doxygen route is definitely very appealing for new code,
 > but converting the existing sources would be a huge amount of work.

Yes, I'm trying to plan for std::tr1 too.
Probably the existing reference guide can be maintained as it is (in HTML)
and 
slowly migrated to Doxygen in case we decide to go for it; the decision can
be 
taken based on the results of a prototype.
I will be unavailable this month but can certainly spend the first week of 
October creating the prototype for a subset of the classes/functions of the
doc 
(maybe Marc can point me to the subset that makes more sense, which has to 
include tables, lists, ...).

 > The stdlib reference, as you know, is large. A cut and paste
 > approach has a number of factors that would make it both tedious and time
 > intensive:
 > care in accurately matching each description with its method signature;

ok

 > chopping the continuous lines of the current documentation into
 > 80 character line lengths for insertion into the code;

Emacs does it for you

 > adding doxygen
 > comment tagging to each description.

this is the real work

 > Then, too, there is the issue of
 > conditional compilation, which doxygen can deal with, but the technique
for
 > doing that is a bit complex.

doxygen lets you specify a set of header files with all the macros that you 
would like to be defined (let's call this set the "bootstrap macro subset")
doxygen will then take that into account when preprocessing the code.

 > We do not really deal with conditional
 > compilation in our current documentation, but I think we will have to
with
 > doxygen because it preprocesses the code before extracting the
 > documentation. (Actually, you can disable preprocessing, but I am
guessing
 > that would create more problems than it would avoid.)

we have then several options:
- generate specific documentation for each supported compiler (that is, for
each 
supported bootstrap macro subset)
- create a documentation-specific bootstrap macro subset
- anything in between the above


 > Maybe Alessio has some automation solutions in mind that would reduce the
 > time. I can think of a few possibilities, but I am uncertain how truly
 > effective they would be. It might be that the effort to get the
automation
 > working well would exceed the time ultimately saved.

we can have a clear idea about that after the prototype has been built
I hope October will be timely enough for the project deadlines (BTW, which
are 
the deadlines?)