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

Subject: Re: [boost] [chrono] v0.4.5 Documentation update + warnings removal +�ug fixes
From: Stewart, Robert (Robert.Stewart_at_[hidden])
Date: 2010-08-13 08:43:50

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.

> > 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."

> > 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."

> 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?"

> > 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).

That's a better way to handle it.

> > _____________
> > 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.

> > _____________
> > 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/.

> > 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.

> > _____
> > 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.

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."

_____
Rob Stewart                           robert.stewart_at_[hidden]
Software Engineer, Core Software      using std::disclaimer;
Susquehanna International Group, LLP  http://www.sig.com


IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.