[Boost-docs] few comments

From: Pavol Droba (droba_at_[hidden])
Date: 2003-07-02 13:19:35

Hi,

I have tried to generate a sample documentation for the string_algo lib using BoostBook 
and Doxygen. Process was a little bit painfull, but the result is quite reasonable. 

I have a few comments and wishes.

1) Generation process.

-	I had to modify  boost/tools/build/tools/doxygen.jam file.
        It contains quotes in the echo command ( for generating the doxygen file ).
        These quotes are not handled well under Windows platform. I had to remove then.
        This file also contained hard-coded path in 'rule extract-xml' ( Being not bjam expert,
   I have changed it to point directly to my files ).

-  Generation process always overrides the doxygen file. It would be handy to be able
   to modify this file, to tune some of doxygen's parameters. So it would be nice,
        if the file is not generated over and over again, just modified when needed.
        Or there could be some possibility to merge user part of doxygen file with 
        a generated one.
        
-  From some unknown reason 'xslt-xsltproc-dir html/HTML.manifest' step takes
   very long time to complete. I assume that I have misconfigured something.
   I have followed the boost-book guide and downloaded xsl and dtd into my
        harddrive, but they are probably not used. ( My Jamfile is included at the end )

2) Generated output

- First of all it looks much better then anything I have tried so far :)

- There are some parts missing in the generated docs. For example parameters descriptions
  are not there ( although they are in the file and doxygen recognized them ).

- I wish there will be some more doxygen parameters recognized. For instance, 
  the file description ( \file tag ) or examples ( \example tag ).

- In my example, template functions have rather long return value and the result currently 
  does not look very nice ( see http://lenin.felcer.sk/~droba/boost-book/ ).
  I don't know if it is feasible, but return type should go on separate line if it is
  longer then some reasonable limit and possibly ( secret wish :) ) splited into several lines.

- Doxygen is able to create links to different components of the documentation directly in
  defintions. I would like to create link for types and template paramters. ( something
  like this: http://www.boost.org/libs/utility/transform_iterator.htm ).

That's all for now. I will post more as I will progress with the documentation.
Thaks for your efford, good job :)

Regards, 

Pavol

PS: One off-topic question. Isn't there any alternative for accessing boost cvs? I have just user
    access. It usualy get 20 of more tries to get a connection and then a very very long time
    to update the repository :(

My Jamfile:

<Jamfile.v2>
import toolset : using ;

using xsltproc ;
using boostbook : /cygdrive/d/docbook/xsl/
                                         : /cygdrive/d/docbook/dtd/
                                         ;

using doxygen ;

project string_algo ;
import boostbook : boostbook ; 
import doxygen : doxygen ;

doxygen find.doxygen : ../../string_algo/boost/string_algo/find.hpp ;
boostbook find : find.doxygen ;

</Jamfile.v2>