Minor tweaks to API documentation and code comments.

mojo/public/c/system/functions.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 basic functions common to different Mojo system APIs.
 //
 // Note: This header should be compilable as C.
 
 #ifndef MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_
 #define MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_
 
-// Note: This header should be compilable as C.
-
 #include "mojo/public/c/system/system_export.h"
 #include "mojo/public/c/system/types.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 // Note: Pointer parameters that are labelled "optional" may be null (at least
 // under some circumstances). Non-const pointer parameters are also labeled
 // "in", "out", or "in/out", to indicate how they are used. (Note that how/if
 // such a parameter is used may depend on other parameters or the requested
 // operation's success/failure. E.g., a separate |flags| parameter may control
 // whether a given "in/out" parameter is used for input, output, or both.)
 
-// Platform-dependent monotonically increasing tick count representing "right
-// now." The resolution of this clock is ~1-15ms. Resolution varies depending
-// on hardware/operating system configuration.
+// Returns the amount of time, in units of microseconds, that has passed since

[viettrungluu, 2015/01/30 22:34:17]

Generally, this is overly verbose.

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

OK, I made it shorter.

+// some undefined point in the past. The values are only meaningful relative to
+// other values obtained from the same device without an intervening system
+// restart. Such values are guaranteed to be weakly monotonically-increasing
+// with the passage of real time, meaning they will not always advance, but they
+// will never go backwards (unlike time values with a well-defined epoch).

[viettrungluu, 2015/01/30 22:34:17]

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.

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

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.

+// Although the units are microseconds, the values should not be assumed to be
+// at that level of precision. The actual precision varies depending on hardware
+// and platform, and is typically in the range of ~1-15 ms.
 MOJO_SYSTEM_EXPORT MojoTimeTicks MojoGetTimeTicksNow(void);
 
 // Closes the given |handle|.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle.
 //
 // Concurrent operations on |handle| may succeed (or fail as usual) if they
 // happen before the close, be cancelled with result |MOJO_RESULT_CANCELLED| if
@@ skipping 23 matching lines @@
 //       thread) during the wait.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle (e.g., if
 //       it has already been closed). The |signals_state| value is unchanged.
 //   |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of
 //       the signals being satisfied.
 //   |MOJO_RESULT_FAILED_PRECONDITION| if it becomes known that none of the
 //       signals in |signals| can ever be satisfied (e.g., when waiting on one
 //       end of a message pipe and the other end is closed).
 //
 // If there are multiple waiters (on different threads, obviously) waiting on
-// the same handle and signal, and that signal becomes is satisfied, all waiters
+// the same handle and signal, and that signal becomes satisfied, all waiters
 // will be awoken.
 MOJO_SYSTEM_EXPORT MojoResult
 MojoWait(MojoHandle handle,
          MojoHandleSignals signals,
          MojoDeadline deadline,
          struct MojoHandleSignalsState* signals_state);  // Optional out.
 
 // Waits on |handles[0]|, ..., |handles[num_handles-1]| until:
 //   - (At least) one handle satisfies a signal indicated in its respective
 //     |signals[0]|, ..., |signals[num_handles-1]|.
@@ skipping 39 matching lines @@
              uint32_t num_handles,
              MojoDeadline deadline,
              uint32_t* result_index,                          // Optional out
              struct MojoHandleSignalsState* signals_states);  // Optional out
 
 #ifdef __cplusplus
 }  // extern "C"
 #endif
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_