> 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.
Glad to hear it! I'm obviously still working on the process, but your feedback helps quite a bit. > 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. Ah, right. The "echo" on Window is surprisingly hard to use for a programmer, but the bjam print module should help > 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 ). Okay, thanks. > - 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. I _think_ the Boost.Jam way would be to define features for Doxygen's parameters, so that instead of writing out a Doxygen configuration file by hand you would just supply some features to the Doxygen module and it would map them to Doxygen parameters. Perhaps its not worth it, and in any case a good interem solution would be to allow a "configuration override" file that is appended to the BoostBook-created file. The reason we regenerate the file each time is that we need to override some of the settings, and it makes _sure_ that we can find the resulting files. > - 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 ) One way to check this would be to add "--nonet" to the xsltproc command line. That will tell you if it tries to download something off the 'net for processing. > 2) Generated output > > - First of all it looks much better then anything I have tried so far :) Woohoo! > - 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 ). Thanks for reporting this. Both are easily fixed. > - I wish there will be some more doxygen parameters recognized. For instance, > the file description ( \file tag ) or examples ( \example tag ). I'll look into it. In general, once I know a feature is missing it's easy to add as long as its in the Doxygen XML in a usable format. > - 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. It's feasible. Actually, I thought I'd already coded it, but obviously that's not the case :). > - 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 ). Again, I'll look into it. I'm not quite sure how it will fit with Doxygen, but the goal for template parameters is that they will be declared to model certain concepts (concepts will also be represented in BoostBook, by way of Caramel), and BoostBook will create links from template parameters to the concepts they model. > That's all for now. I will post more as I will progress with the documentation. Thank you. > <Jamfile.v2> > import toolset : using ; > > using xsltproc ; > using boostbook : /cygdrive/d/docbook/xsl/ > : /cygdrive/d/docbook/dtd/ > ; > > using doxygen ; The chunk of code above should really go into the user-config.jam in , e.g., $BOOST_ROOT/tools/build, because these are user-specific preferences. The Jamfile.v2 should contain the other rules that describe how to build the documentation. Doug ------------------------------------------------------- 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
