Minor tweaks to API documentation and code comments.

Minor tweaks to API documentation and code comments.

R=viettrungluu@chromium.org

Committed: https://chromium.googlesource.com/external/mojo/+/90561de525b3f5708ab8c3b07af502927ae67c9e

[ggowan, 2015-01-16 06:00:57]

ggowan@google.com changed reviewers:
+ viettrungluu@chromium.org

[viettrungluu, 2015-01-16 17:32:26]

https://codereview.chromium.org/847703006/diff/1/mojo/public/c/system/types.h
File mojo/public/c/system/types.h (right):

https://codereview.chromium.org/847703006/diff/1/mojo/public/c/system/types.h...
mojo/public/c/system/types.h:20: // |MojoTimeTicks|: Platform-dependent,
monotonically increasing tick count
This comment is strictly worse than the previous version.
a) The type is not platform-dependent.
b) The unit is always microseconds.
c) Resolution is not a function of the type.
d) This type may be used by things other than MojoGetTimeTicksNow().

[ggowan, 2015-01-16 23:30:34]

Thanks for the review! Please take another look.

https://codereview.chromium.org/847703006/diff/1/mojo/public/c/system/types.h
File mojo/public/c/system/types.h (right):

https://codereview.chromium.org/847703006/diff/1/mojo/public/c/system/types.h...
mojo/public/c/system/types.h:20: // |MojoTimeTicks|: Platform-dependent,
monotonically increasing tick count
On 2015/01/16 17:32:26, viettrungluu wrote:
> This comment is strictly worse than the previous version.
> a) The type is not platform-dependent.
> b) The unit is always microseconds.
> c) Resolution is not a function of the type.
> d) This type may be used by things other than MojoGetTimeTicksNow().

Thanks for the feedback. I was confused by the different comments in two
different places which seemed contradictory to me, but now I understand what was
meant.

I don't think values of this type will be generated in any way other than by
calling MojoGetTimeTicksNow() because the epoch is unspecified, so nobody would
know how to generate the value correctly. Given that, I think the  meaning of
the type is tightly bound to the meaning of the MojoGetTimeTicksNow() function.
Rather than splitting the meaning between two different comments in two
different files, I prefer to make one comprehensive comment describing the time
measurements, and to repeat that comment in both locations.

I've updated the comment to include the fact that it is in units of microseconds
and to clarify the other points. Please take another look.

[ggowan, 2015-01-28 01:26:21]

Hi Viet-Trung,

It's been 11 days of silence on this CL. It seemed you only had concerns around
the MojoTimeTicks comment in types.h. If you don't have time to respond to me on
that part, would it help move things along if I simply remove that part from
this CL?

Thanks,
Geoff

On 2015/01/16 23:30:34, ggowan wrote:
> Thanks for the review! Please take another look.
> 
> https://codereview.chromium.org/847703006/diff/1/mojo/public/c/system/types.h
> File mojo/public/c/system/types.h (right):
> 
>
https://codereview.chromium.org/847703006/diff/1/mojo/public/c/system/types.h...
> mojo/public/c/system/types.h:20: // |MojoTimeTicks|: Platform-dependent,
> monotonically increasing tick count
> On 2015/01/16 17:32:26, viettrungluu wrote:
> > This comment is strictly worse than the previous version.
> > a) The type is not platform-dependent.
> > b) The unit is always microseconds.
> > c) Resolution is not a function of the type.
> > d) This type may be used by things other than MojoGetTimeTicksNow().
> 
> Thanks for the feedback. I was confused by the different comments in two
> different places which seemed contradictory to me, but now I understand what
was
> meant.
> 
> I don't think values of this type will be generated in any way other than by
> calling MojoGetTimeTicksNow() because the epoch is unspecified, so nobody
would
> know how to generate the value correctly. Given that, I think the  meaning of
> the type is tightly bound to the meaning of the MojoGetTimeTicksNow()
function.
> Rather than splitting the meaning between two different comments in two
> different files, I prefer to make one comprehensive comment describing the
time
> measurements, and to repeat that comment in both locations.
> 
> I've updated the comment to include the fact that it is in units of
microseconds
> and to clarify the other points. Please take another look.

[viettrungluu, 2015-01-30 22:34:18]

https://codereview.chromium.org/847703006/diff/20001/mojo/public/c/system/fun...
File mojo/public/c/system/functions.h (right):

https://codereview.chromium.org/847703006/diff/20001/mojo/public/c/system/fun...
mojo/public/c/system/functions.h:26: // Returns the amount of time, in units of
microseconds, that has passed since
Generally, this is overly verbose.

https://codereview.chromium.org/847703006/diff/20001/mojo/public/c/system/fun...
mojo/public/c/system/functions.h:31: // will never go backwards (unlike time
values with a well-defined epoch).
As far as I know, time travel is still an impossibility, so real time always
advances, as opposed to wall clock times, which may have to be adjusted
(possibly backwards). That is, modulo relativistic effects, "real time since
epoch" is well defined.

https://codereview.chromium.org/847703006/diff/20001/mojo/public/c/system/typ...
File mojo/public/c/system/types.h (right):

https://codereview.chromium.org/847703006/diff/20001/mojo/public/c/system/typ...
mojo/public/c/system/types.h:20: // |MojoTimeTicks|: The amount of time, in
units of microseconds, that has
How about, simply: "A time delta, in microseconds, the meaning of which is
source-dependent."

[ggowan, 2015-01-30 23:17:12]

Thanks for the review. I've addressed all your comments. PTAL

https://codereview.chromium.org/847703006/diff/20001/mojo/public/c/system/fun...
File mojo/public/c/system/functions.h (right):

https://codereview.chromium.org/847703006/diff/20001/mojo/public/c/system/fun...
mojo/public/c/system/functions.h:26: // Returns the amount of time, in units of
microseconds, that has passed since
On 2015/01/30 22:34:17, viettrungluu wrote:
> Generally, this is overly verbose.

OK, I made it shorter.

https://codereview.chromium.org/847703006/diff/20001/mojo/public/c/system/fun...
mojo/public/c/system/functions.h:31: // will never go backwards (unlike time
values with a well-defined epoch).
On 2015/01/30 22:34:17, viettrungluu wrote:
> As far as I know, time travel is still an impossibility, so real time always
> advances, as opposed to wall clock times, which may have to be adjusted
> (possibly backwards). That is, modulo relativistic effects, "real time since
> epoch" is well defined.

If you're talking about a value obtained from a clock on a device that's
supposed to correctly represent the current time (e.g. seconds since 1970), it
may go backwards sometimes because for example the system clock may have been
corrected between the two measurements (which happens automatically). I think
there may even be other possible reasons related to thread/processor context
switches or something. That's what I was referring to. Sorry I didn't make it
more clear. 

Anyway, I've removed that bit to try to shorten the paragraph. I included it
because I thought it helped to justify why somebody should consider using this
tick count time value with undefined epoch instead of a more typical clock time
with a well-defined epoch. If you feel it was actually helpful, I'll be happy to
put it back in.

https://codereview.chromium.org/847703006/diff/20001/mojo/public/c/system/typ...
File mojo/public/c/system/types.h (right):

https://codereview.chromium.org/847703006/diff/20001/mojo/public/c/system/typ...
mojo/public/c/system/types.h:20: // |MojoTimeTicks|: The amount of time, in
units of microseconds, that has
On 2015/01/30 22:34:17, viettrungluu wrote:
> How about, simply: "A time delta, in microseconds, the meaning of which is
> source-dependent."

I think that somebody who is coming here to look at this definition would
probably also appreciate a reference to the MojoGetTimeTicksNow() function,
which, practically speaking, is the only place values of this type are likely to
come from.

However, I'll just put the text you've asked for since it's definitely an
improvement over what's there now. If you agree a reference to the function is
appropriate, I'll be happy to add it, perhaps in a follow-up CL.

[viettrungluu, 2015-01-30 23:45:42]

lgtm w/nit

https://codereview.chromium.org/847703006/diff/40001/mojo/public/c/system/fun...
File mojo/public/c/system/functions.h (right):

https://codereview.chromium.org/847703006/diff/40001/mojo/public/c/system/fun...
mojo/public/c/system/functions.h:28: // from the same device without an
intervening system restart.  Such values are
nit: one space after '.'

[ggowan, 2015-01-31 00:44:15]

Thanks for the review and for catching that.

https://codereview.chromium.org/847703006/diff/40001/mojo/public/c/system/fun...
File mojo/public/c/system/functions.h (right):

https://codereview.chromium.org/847703006/diff/40001/mojo/public/c/system/fun...
mojo/public/c/system/functions.h:28: // from the same device without an
intervening system restart.  Such values are
On 2015/01/30 23:45:42, viettrungluu wrote:
> nit: one space after '.'

Done.

[ggowan, 2015-01-31 00:59:32]

Committed patchset #4 (id:60001) manually as
90561de525b3f5708ab8c3b07af502927ae67c9e (presubmit successful).