Minor tweaks to API documentation and code comments.

mojo/public/c/system/types.h

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // This file contains types and constants/macros common to different Mojo system
 // APIs.
 //
 // Note: This header should be compilable as C.
 
 #ifndef MOJO_PUBLIC_C_SYSTEM_TYPES_H_
 #define MOJO_PUBLIC_C_SYSTEM_TYPES_H_
 
 #include <stdint.h>
 
 #include "mojo/public/c/system/macros.h"
 
 // TODO(vtl): Notes: Use of undefined flags will lead to undefined behavior
 // (typically they'll be ignored), not necessarily an error.
 
-// |MojoTimeTicks|: Used to specify time ticks. Value is in microseconds.
+// |MojoTimeTicks|: Platform-dependent, monotonically increasing tick count

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

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

+// representing time.  The resolution of this clock is ~1-15ms.  Resolution
+// varies depending on hardware/operating system configuration.
 
 typedef int64_t MojoTimeTicks;
 
 // |MojoHandle|: Handles to Mojo objects.
 //   |MOJO_HANDLE_INVALID| - A value that is never a valid handle.
 
 typedef uint32_t MojoHandle;
 
 #ifdef __cplusplus
 const MojoHandle MOJO_HANDLE_INVALID = 0;
@@ skipping 146 matching lines @@
 // 32-bit-aligned.
 MOJO_STATIC_ASSERT(MOJO_ALIGNOF(int32_t) == 4, "int32_t has weird alignment");
 struct MOJO_ALIGNAS(4) MojoHandleSignalsState {
   MojoHandleSignals satisfied_signals;
   MojoHandleSignals satisfiable_signals;
 };
 MOJO_STATIC_ASSERT(sizeof(MojoHandleSignalsState) == 8,
                    "MojoHandleSignalsState has wrong size");
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_TYPES_H_