----- Original Message ----- From: "Stewart, Robert" <Robert.Stewart@sig.com> To: <boost@lists.boost.org> 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_chr.... 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