Minor tweaks to API documentation and code comments.

mojo/public/c/system/functions.h

Index: mojo/public/c/system/functions.h
diff --git a/mojo/public/c/system/functions.h b/mojo/public/c/system/functions.h
index 5e0a0c414df9dfd88afabb91e18c3ce75f86b11d..45f96b6f238fbb5eb8a1790447cc9434dc1ff8ba 100644
--- a/mojo/public/c/system/functions.h
+++ b/mojo/public/c/system/functions.h
@@ -9,8 +9,6 @@
 #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"
 
@@ -25,9 +23,15 @@ extern "C" {
 // 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|.
@@ -71,7 +75,7 @@ MOJO_SYSTEM_EXPORT MojoResult MojoClose(MojoHandle handle);
 //       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,