Re: [boost] [chrono] v0.4.5 Documentation update +=D=A=9_warnings removal +�ug fixes

Subject: Re: [boost] [chrono] v0.4.5 Documentation update +=D=A=9_warnings removal +�ug fixes
From: vicente.botet (vicente.botet_at_[hidden])
Date: 2010-08-13 13:03:38

----- Original Message ----- 
From: "Stewart, Robert" <Robert.Stewart_at_[hidden]>
To: <boost_at_[hidden]>
Sent: Friday, August 13, 2010 2:43 PM
Subject: Re: [boost] [chrono] v0.4.5 Documentation update + warnings removal +�ug fixes

> 
> vicente.botet wrote:
>> Rob Stewart wrote:
>> > vicente.botet wrote:
>>
>> > _____________
>> > Description
>> >
>> > Para 1, bullet 3:
>> >
>> > s/any given/a particular/
>> > s/symbolic bundle/pairing/
>>
>> As Clocks are not instantiated, what about "symbolic pairing"?
> 
> I don't think the distinction is helpful.  Clock is a concept that pairs time_point and duration.  As a concept, it is understood that it isn't instantiated.

OK.
 
>> > 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.
> 
> Actually, "platform native time point" might be better.  Otherwise, just "time_point."

I left just time_point.

>> > Para 3, bullet 2:
>> >
>> > 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> >.
> 
> This sort of description should appear here: http://svn.boost.org/svn/boost/sandbox/chrono/libs/chrono/doc/html/boost_chrono/reference/reporters.html#boost_chrono.reference.reporters.stopclock_hpp.stopclock.  That is: "A stopclock is a stopwatch with the ability to report elapsed time on an output stream."

Done.
 
>> If the name is confusing, I will need to find a better one.
>> Any suggestions?
> 
> The name in no way represents the class' purpose or behavior, so a different name is definitely in order.  I imagine you settled on "stopclock" because you wanted to avoid a long name.  My first thought is that stopwatch_reporter<stopwatch<Clock>> is the better spelling because it clearly shows that the reporting functionality is being added to a stopwatch.  However, a non-nested class template is simpler to write and gives a name to the feature, so how about the direct and obvious "reporting_stopwatch?"

What others think? Other suggestions for the shortcut?
 
>> > _____________
>> > 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.
> 
> My point was that you indicated a set of multiple include directives should be assumed for all examples.  I would expect a single include directive to have covered the examples.

OK. I will suppose every example includes  
    #include <boost/stopwatches.hpp>

>> > _____________
>> > Motivation
>> >
>> > _____
>> > Reporting slapsed[sic] time
>> >
>> > Para 1, last sentence:
>> >
>> > I'm not sure what you mean by "allowing to make a single measure."
>>
>> I will remove this part of the sentence.
> 
> I think that's better.  Now, BTW, s/the measure of the/measuring/.

Done.
 
>> > 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."
> 
> Did you miss this one?  I think you should mention reporting uses other than the display and a log file seems a good choice.  I also don't like "at the user level" as the introduction to this paragraph.

Yes. Done now.
 
>> > _____
>> > 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.
> 
> There's too much detail here for the Motivation section.  Besides, to motivate the use of the library, you don't need to explain deficiencies and provisions to overcome them.  This belongs elsewhere.  There should be a FAQ or Implementation Issues section for details like you have here.

I've moved to the Rationale section. 

> If you still think something should be in the Motivation section, maybe this will be enough:
> 
> "There are a number of things that can lead to unreliable measurement (see [here] for more details), but they mostly amount to reporting overhead.  Boost.Chrono provides two ways to improve reliability of time measurements.  A [stopwatch_accumulator] only reports statistics once all measurements have been acquired, which removes reporting overhead from the measurements.  The other approach is to use a [SuspendibleClock] such that the reporting overhead can be ignored by suspending elapsed time tracking during reporting operations."

Yes, this should be enough.

Thanks again,
Vicente