[docs][crc] Did I do new documentation correctly?
I completely redid the documentation for Boost.CRC in changeset [76335]. It uses Doxygen and Quickbook. I guessed on how to do it by copying files from Boost.Move. But I only did stuff within the BOOST_ROOT/libs/crc/* directory. I didn't make changes to other directories, especially the BOOST_ROOT/doc/* directory. Is stuff in that directory supposed to be automatically built? Other concerns: 1. The quickbook/doxygen system doesn't seem to handle "\todo" constructs correctly. 2. Is there a way to #define various common macros, like BOOST_STATIC_CONSTANT, so they get expanded correctly in Doxygen? Is there a "Doxyfile," or can the needed Doxygen parameters be tweaked in the Jamfile.v2? 3. I guessed that the next release will be "1.49.0", is that right? 4. Content-wise, did I miss anything? Daryle W.
On 7 January 2012 03:57, Daryle Walker <darylew@hotmail.com> wrote:
I completely redid the documentation for Boost.CRC in changeset [76335]. It uses Doxygen and Quickbook. I guessed on how to do it by copying files from Boost.Move. But I only did stuff within the BOOST_ROOT/libs/crc/* directory. I didn't make changes to other directories, especially the BOOST_ROOT/doc/* directory. Is stuff in that directory supposed to be automatically built?
You can either add it to the combined documentation so that it's built under 'doc/html', or I can add your documentation to my build script so that it's built in place. The latter is probably easiest as you don't have to deal with the documentation being built in two different locations. I'll try adding it tonight. You didn't need to check in copies of the images and css files, it should use the shared files automatically (which are in the 'doc/src' directory).
Date: Sat, 7 Jan 2012 15:53:26 +0000 From: dnljms@gmail.com
On 7 January 2012 03:57, Daryle Walker wrote:
I completely redid the documentation for Boost.CRC in changeset [76335]. It uses Doxygen and Quickbook. I guessed on how to do it by copying files from Boost.Move. But I only did stuff within the BOOST_ROOT/libs/crc/* directory. I didn't make changes to other directories, especially the BOOST_ROOT/doc/* directory. Is stuff in that directory supposed to be automatically built?
You can either add it to the combined documentation so that it's built under 'doc/html', or I can add your documentation to my build script so that it's built in place. The latter is probably easiest as you don't have to deal with the documentation being built in two different locations. I'll try adding it tonight.
You didn't need to check in copies of the images and css files, it should use the shared files automatically (which are in the 'doc/src' directory).
So, should I remove the copies I added in the BOOST_ROOT/libs/crc/doc/ directory? When I was building the HTML docs, the files were put into the CRC doc directory, where I guess it was using those files. Daryle W.
On 7 January 2012 23:31, Daryle Walker <darylew@hotmail.com> wrote:
So, should I remove the copies I added in the BOOST_ROOT/libs/crc/doc/ directory? When I was building the HTML docs, the files were put into the CRC doc directory, where I guess it was using those files.
Yes. When you build outside of the boost directory it does that, as it doesn't have a shared copy of the files, but inside the boost directory it uses the shared copies so you don't need your own. This happens because of a parameter set in Jamroot which tells boostbook that it's in the boost directory, and the boost.root parameter you set which tells it where to find the root. You can see the docs I built last night at: http://boost-sandbox.sourceforge.net/libs/crc/doc/html/ When you merge to release the script should pick that up and start building the documentation for the release snapshots.
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Daryle Walker Sent: Saturday, January 07, 2012 3:57 AM To: boost@lists.boost.org Subject: [boost] [docs][crc] Did I do new documentation correctly?
I completely redid the documentation for Boost.CRC in changeset [76335]. It uses Doxygen and Quickbook.
Looks rather nice (and quite complete) - at a quick glance.
Other concerns: 1. The quickbook/doxygen system doesn't seem to handle "\todo" constructs correctly.
This is a TODO ;-)
2. Is there a way to #define various common macros, like BOOST_STATIC_CONSTANT, so they get expanded correctly in Doxygen?
You can find various examples of people dealing this problem - I've collected some examples at https://svn.boost.org/svn/boost/sandbox/tools/quick_auto_dox_index/libs/quic... file.v2
Is there a "Doxyfile," or can the needed Doxygen parameters be tweaked in the Jamfile.v2?
Yes - tweak via your jamfile.v2. The above file is over-documented to document the many possibilities. You might like to enforce documentation of all functions - and then get a report of any missing their documentation in a warnings.log file?
3. I guessed that the next release will be "1.49.0", is that right?
I believe so, but time is short?
4. Content-wise, did I miss anything?
History of trac items dealt with? mods etc? None of the macros are Doxygen documented. This might be useful for some users? How about an index? This can be produced automatically using John Maddock's autoindex. http://www.boost.org/doc/libs/1_48_0/tools/auto_index/doc/html/index.html You will need to put some work into an crc.idx file for the users to get most out of it, but even just feeding everything through will be better than nothing - will index all functions and macros. For an example to follow, you might find Pierre Talbot's Checks Google Summer of Code project helpful. His documentation uses all the tools quite fully, including an index. See his checks.idx file for an example - you can probably use some of his index entries directly https://svn.boost.org/svn/boost/sandbox/SOC/2011/checks/libs/checks/doc/ Keep up the good work ;-) Paul --- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow@hetp.u-net.com
participants (3)
-
Daniel James -
Daryle Walker -
Paul A. Bristow