[boost] [chrono] Documentation suggestions

Subject: [boost] [chrono] Documentation suggestions
From: Roland Bock (rbock_at_[hidden])
Date: 2010-06-23 09:27:44

Hi,

I have a few remarks/suggestions for the documentation of Boost.Chrono:

*General:
*http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/index.html

There are several sections which attract my attention when trying to get
a grip on the library:

    * Getting Started
    * Tutorial
    * Examples

Each of those looks a bit like a random collection of valuable hints to
me (sorry, if I missed the pattern). My personal troubles in
understanding the basics are documented in the mail referenced in the
tutorial section.

I think it would be worth it to reorganize all three into one section
(e.g. tutorial) which shows how to utilize the different parts of the
library. For instance with the following subsections:

    * Clocks (including stopwatch and thread_clock)
    * Formatters
    * Reporters
    * Conversions (see also Tutorial section below)
    * ...?

Each section would contain usage patterns and complete sample programs.

*Users Guide:
*http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide.html

    * Personally, I would move the references section to the appendices
      (I clicked there several times when I really wanted to see the
      Reference section)

*Reference:
*http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/reference.html

    * thread_clock is missing in the reference section
    * typo "chorno.hpp>" on several pages

*Examples:*
http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/examples.html

    * There are several hints like "See the file
      i_dont_like_the_default_duration_behavior.cpp". It would be nice
      to have a working link to the file instead
    * Some examples are not linked to a file. I think it would be good
      to have a working sample file for each example

*Tutorial:*
http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide/tutorial.html

    * The section "How to define a thread clock" is now obsolete, isn't
      it? thread_clock is now integral part of chrono.
    * An example on how to use the thread_clock would be very helpful.
    * An example on how to obtain a duration in some unit would be helpful

See here (http://lists.boost.org/boost-users/2010/04/58204.php) for what
I meant with the last item. The answers by Howard Hinnant in this mail
were extremely helpful and could probably be re-used in the tutorial.

Regards,

Roland