incubator-stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Lance Diduck" <>
Subject RE: stdcxx documentation format
Date Wed, 07 Sep 2005 10:54:27 GMT

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){

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 
    #define TYPENAME   typename
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,...);

#if !(defined( __SUNPRO_CC )) 
    template<typename tr1_templateargU>  
    struct is_class:integral_constant<bool,
        == sizeof(detail::yes_type))> {

-----Original Message-----
From: Alessio Marchetti [] 
Sent: Wednesday, September 07, 2005 6:01 AM
Cc: Martin Sebor; Marc Betz
Subject: Re: stdcxx documentation format

My comments below...


 > 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)
slowly migrated to Doxygen in case we decide to go for it; the decision can
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
(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;


 > 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
 > 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
 > doxygen because it preprocesses the code before extracting the
 > documentation. (Actually, you can disable preprocessing, but I am
 > that would create more problems than it would avoid.)

we have then several options:
- generate specific documentation for each supported compiler (that is, for
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
 > 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
the deadlines?)

View raw message