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>
-------------------------------------------------------
This SF.Net email sponsored by: Free pre-built ASP.NET sites including
Data Reports, E-commerce, Portals, and Forums are available now.
Download today and enter to win an XBOX or Visual Studio .NET.
http://aspnet.click-url.com/go/psa00100006ave/direct;at.asp_061203_01/01
_______________________________________________
Boost-docs mailing list
[EMAIL PROTECTED]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
