Update platform handle (private) API "documentation"/comments.

mojo/public/platform/native/platform_handle_private.h

Index: mojo/public/platform/native/platform_handle_private.h
diff --git a/mojo/public/platform/native/platform_handle_private.h b/mojo/public/platform/native/platform_handle_private.h
index adda510073f877d80108cc0fbf0e21815da2cd86..25f991f501694d978ca86e8b9fa32585445eb1b1 100644
--- a/mojo/public/platform/native/platform_handle_private.h
+++ b/mojo/public/platform/native/platform_handle_private.h
@@ -8,25 +8,61 @@
 #include "mojo/public/c/system/handle.h"
 #include "mojo/public/c/system/result.h"
 
-typedef int MojoPlatformHandle;  // Unix file descriptor
+// |MojoPlatformHandle|: Type for "platform handles", i.e., the underlying OS's
+// handles. Currently this is always just a Unix file descriptor.
+
+typedef int MojoPlatformHandle;
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-// Wraps |platform_handle| in a MojoHandle so that it can transported. Returns
-// MOJO_RESULT_OK on success, all other results indicate failure. This takes
-// ownership of |platform_handle|, regardless of whether this succeeds.
-MojoResult MojoCreatePlatformHandleWrapper(MojoPlatformHandle platform_handle,
-                                           MojoHandle* wrapper);
-
-// Extracts |platform_handle| from |wrapper|. Returns MOJO_RESULT_OK on success,
-// all other results indicate failure. If this succeeds, it causes |wrapper| to
-// relinquish ownership of |platform_handle|, so MojoClose'ing |wrapper| will no
-// longer close the underlying |platform_handle|. Never the less, it is still
-// neccessary to MojoClose |wrapper|, but this will not affect the underlying
-// descriptor after this call.
-MojoResult MojoExtractPlatformHandle(MojoHandle wrapper,
+// |MojoCreatePlatformHandleWrapper()|: Creates a |MojoHandle| that wraps (and
+// takes ownership of) the platform handle |platform_handle|, which must be
+// valid.
+//
+// On success, |*platform_handle_wrapper_handle| will be set to the wrapper
+// handle. It will have (at least) the |MOJO_HANDLE_RIGHT_TRANSFER|,
+// |MOJO_HANDLE_RIGHT_READ|, and |MOJO_HANDLE_RIGHT_WRITE| rights. Warning: No
+// validation of |platform_handle| is done. (TODO(vtl): This has poor/annoying
+// implications, since we may detect this when we transfer the wrapper handle.)
+//
+// Warning: On failure, this will still take ownership of |platform_handle|

[azani, 2016/05/10 21:15:35]

Maybe this is a bit clearer:

Warning: On failure, this function will still take ownership of
|platform_handle| (which just means that |platform_handle| will be closed).

+// (which just means that it will close it).
+//
+// Returns:
+//   |MOJO_RESULT_OK| on success.
+//   |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has
+//       been reached (e.g., if the maximum number of handles was exceeded).
+MojoResult MojoCreatePlatformHandleWrapper(
+    MojoPlatformHandle platform_handle,
+    MojoHandle* platform_handle_wrapper_handle);
+
+// |MojoExtractPlatformHandle()|: Extracts the wrapped platform handle from
+// |platform_handle_wrapper_handle| (which must have both the
+// |MOJO_HANDLE_RIGHT_READ| and |MOJO_HANDLE_RIGHT_WRITE| rights).
+//
+// On success, |*platform_handle| will be set to the wrapped platform handle and
+// ownership of the wrapped platform handle will be passed to the caller (i.e.,
+// closing |platform_handle_wrapper_handle| will no longer close the platform
+// handle).
+//
+// Warnings:
+//   - Even though |platform_handle_wrapper_handle| is then basically useless
+//     (it no longer "contains" a platform handle), it must still be closed as
+//     usual.
+//   - If the wrapped platform handle has already been extracted from
+//     |platform_handle_wrapper_handle|, then this will still succeed, but
+//     |*platform_handle| will be set to -1.
+//
+// Returns:
+//   |MOJO_RESULT_OK| on success.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
+//       |platform_handle_wrapper_handle| is not a valid wrapper handle).
+//   |MOJO_RESULT_PERMISSION_DENIED| if |platform_handle_wrapper_handle| does
+//       not have the both the |MOJO_HANDLE_RIGHT_READ| and
+//       |MOJO_HANDLE_RIGHT_WRITE| rights.
+MojoResult MojoExtractPlatformHandle(MojoHandle platform_handle_wrapper_handle,
                                      MojoPlatformHandle* platform_handle);
 
 #ifdef __cplusplus