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

R=azani@chromium.org

Review URL: https://codereview.chromium.org/1970513002 .

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 adda510..8e46d6a 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);
+// |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|
+// (which just means that |platform_handle| will be closed).
+//
+// 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);
 
-// 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,
+// |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

mojo/public/platform/native/platform_handle_private_thunks.c

diff --git a/mojo/public/platform/native/platform_handle_private_thunks.c b/mojo/public/platform/native/platform_handle_private_thunks.c
index 9c0b35b..b10607e 100644
--- a/mojo/public/platform/native/platform_handle_private_thunks.c
+++ b/mojo/public/platform/native/platform_handle_private_thunks.c
@@ -10,16 +10,19 @@
 
 static struct MojoPlatformHandlePrivateThunks g_thunks = {0};
 
-MojoResult MojoCreatePlatformHandleWrapper(MojoPlatformHandle platform_handle,
-                                           MojoHandle* wrapper) {
+MojoResult MojoCreatePlatformHandleWrapper(
+    MojoPlatformHandle platform_handle,
+    MojoHandle* platform_handle_wrapper_handle) {
   assert(g_thunks.CreatePlatformHandleWrapper);
-  return g_thunks.CreatePlatformHandleWrapper(platform_handle, wrapper);
+  return g_thunks.CreatePlatformHandleWrapper(platform_handle,
+                                              platform_handle_wrapper_handle);
 }
 
-MojoResult MojoExtractPlatformHandle(MojoHandle wrapper,
+MojoResult MojoExtractPlatformHandle(MojoHandle platform_handle_wrapper_handle,
                                      MojoPlatformHandle* platform_handle) {
   assert(g_thunks.ExtractPlatformHandle);
-  return g_thunks.ExtractPlatformHandle(wrapper, platform_handle);
+  return g_thunks.ExtractPlatformHandle(platform_handle_wrapper_handle,
+                                        platform_handle);
 }
 
 THUNK_EXPORT size_t MojoSetPlatformHandlePrivateThunks(
@@ -27,4 +30,4 @@
   if (thunks->size >= sizeof(g_thunks))
     g_thunks = *thunks;
   return sizeof(g_thunks);
-}
\ No newline at end of file
+}