[boost] Re: [chrono] v0.4.5 Documentation update + warnings removal +›ug fixes

Subject: [boost] Re: [chrono] v0.4.5 Documentation update + warnings removal +›ug fixes
From: vicente.botet (vicente.botet_at_[hidden])
Date: 2010-08-13 04:17:29

Hi, 
thanks for your inside rewording. I have taken most of them in account. Next follows answers to some questions or some questions to your comments.

----- Original Message ----- 
From: "Stewart, Robert" <Robert.Stewart_at_[hidden]>
To: <boost_at_[hidden]>
Sent: Wednesday, August 11, 2010 2:47 PM
Subject: Re: [boost] [chrono] v0.4.5 Documentation update + warnings removal + bug fixes

> 
> vicente.botet wrote:
>>
>> Even if the review's date is not annonced yet, it will be
>> great if some of you make a pre-review, so the conflicting
>> issues are managed before the review.
> 
> Here are comments from my reading of the initial sections of the document.  Hopefully, I can offer comments on the User's Guide another time.

Thanks, this will be very helpful.
 
> _____________
> Overview
> 
> This section appears to be a sibling of the immediately following Description section, but includes a one-item TOC leading to the Motivation section which is also found by following the navigation icons to the next section.  This is confusing.
> 
> I'd expect the Overview section to include a TOC leading to the Motivation section first, and the Description section second, which means moving Description to its own page.  I'd expect the How to Use This Documentation section to remain on the same page as the Overview section.

I have made the Description a section that follows the Motivation.
 
> _____________
> Description
> 
> Para 1, bullet 3:
> 
> s/any given/a particular/
> s/symbolic bundle/pairing/

As Clocks are not instantiated, what about "symbolic pairing"?
 
> What is a "native time_point?"  That phrase suggests there are others, so why the distinction here?

The library works only with time points supported natively by the platform. I can remove native here if this is confusing.
 
> Para 3, bullet 2:
> 
> Given this reference to a "higher layer," one might now infer that the features described in the first two paragraphs were the lower layer, but it would be better to avoid references to layers, at least within the Description section.  You also use the term "stopclock" as though its meaning is apparent.  It isn't.  The description doesn't clearly convey the meaning either.  I looked at the documentation for basic_stopclock and stopclock and found nothing to help.  I can infer that it is to measure elapsed time like a stopwatch, but, perhaps, with less precision, though I have no confidence in that inference.
> 
> I can't suggest how to rewrite this bullet without understanding "stopclock."

I have had a lot of trouble finding a name for the stopclock class. Stopclocks and Stopwatches differ only in one feature: the ability of Stopclocks to report the elapsed time on a output stream, either by an explicit request, or implicitly at the destruction of the Stopclock. A stopclock<Clock> is a synomym of a stopwatch_reporter<stopwatch<Clock> >.
If the name is confusing, I will need to find a better one. Any suggestions?
 
> Para 3, bullet 2, subbullet 3:
> 
> This bullet isn't of much value in this introductory text, particularly as there is no explicit mention of any characters until this point.

Maybe  I need to add that the report is done on an output stream (including wide char streams).

> _____________
> How to Use This Documentation
> 
> Para 2:
> 
> Is there no include all header for Chrono?

We can  consider that the current package has 4 libraries:
* common_type for type_traits
* ratio
* chrono
* stropwatches

When we include boost/chrono.hpp we include only the standard. Of course this includes also the 
    #include <boost/type_traits/common_type.hpp>
    #include <boost/ratio.hpp>

We can consider that 

    #include <boost/stopwatches.hpp>

is the top level include file.
 
> _____________
> Motivation
> 
> This section should precede the Description section.  It is here that you're trying to sell the library.  Once hooked, the reader will want to read a description.
> 
> _____
> Reporting slapsed[sic] time
> 
> Para 1, last sentence:
> 
> I'm not sure what you mean by "allowing to make a single measure."

This is in oposition to the ability of stopwatch_accumulator to manage with multiple measures samples.
I will remove this part of the sentence.
 
> Para 2, sentence 1:
> 
> Try, "It is often necessary to report elapsed time on a user display or in a log file.  [stopwatch_reporter<>] provides a runtime reporting mechanism for this purpose which can be invoked in just one line of code."
> 
> _____
> How reliable are these measures?
> 
> This section doesn't belong in Motivation.  This should be in the Getting Started section, I think.

This section is the motivation for stopwatches accumulators, and suspendible clocks. Maybe the wording should be improved.  
 

Thanks again, 
Vicente