Re: [boost] [Review] Formal Review of Proposed Boost.Chrono Library Starts TOMORROW

Subject: Re: [boost] [Review] Formal Review of Proposed Boost.Chrono Library Starts TOMORROW
From: Roland Bock (rbock_at_[hidden])
Date: 2010-11-08 15:03:21

On 11/08/2010 06:32 PM, vicente.botet wrote:
>
>    
>> Yes, but the documentation should receive another update.
>>      
> Many thanks. Please, could you point to other documentation improvements?
>
>
>    
Hi Vicente,

here are some more items. I'm sure there's more, but I'm in a bit of a 
hurry and did not go through the document line by line:

http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/overview/description.html

*) "the extraction of read (wall clock) time," <= real? CPU time?
*) "|process_real_cpu_clock| 
<http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/reference/other_clocks.html#boost_chrono.reference.other_clocks.process_cpu_clocks_hpp.process_real_cpu_clock>, 
captures real (wall clock) CPU times." <= is this really CPU time? Isn't 
it rather real process time?
*) "A tuple-like class __process_cpuclock_, that" <= The link is broken.

http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide.html
I'd prefer to see the same sequence of duration, timepoint, clocks, 
other clocks etc. Currently every chapter is different:

- Description:
duration, time_point, clocks, other clocks, io
- Tutorial:
duration, clocks, time_point, io
- Examples:
time_point, duration, clocks, conversions, reporting
- Reference:
duration, time_point, clocks, io, other clocks

Personally, I like Description and Reference best.

http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide/tutorial.html
Taking a look at the table of contents for this section shows that 
duration is covered in much detail, time_point, a bit less. Clock and IO 
seem to be rather neglected. Given the sheer number of different clocks 
available in Chrono, this seems unbalanced.
And taking a closer look at the "Clocks" section shows: The tutorial 
explains the interface of a clock, but not the clocks themselves. What 
is a system clock, what's so cool about a monotonic_clock, what 
distinguishes a high_precision_clock (another damaged link here).

In order to remove confusion about wall time and CPU time, a small 
example using different clocks might be useful (if it is there, I missed 
it). I would like to see this as part of the tutorial.

http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/users_guide/examples.html
- Just stumbled over this: simaulation
- There is no thread_clock mentioned here, even though there is a thread 
interface demonstration program.

Regards,

Roland