Adds lots of Mojo documentation

mojo/public/c/system/buffer.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/constants and functions specific to buffers (and in
-// particular shared buffers).
-// TODO(vtl): Reorganize this file (etc.) to separate general buffer functions
-// from (shared) buffer creation.
+// This file contains types/constants and functions specific to shared buffers.
 //
 // Note: This header should be compilable as C.
 
 #ifndef MOJO_PUBLIC_C_SYSTEM_BUFFER_H_
 #define MOJO_PUBLIC_C_SYSTEM_BUFFER_H_
 
 #include <stdint.h>
 
 #include "mojo/public/c/system/macros.h"
 #include "mojo/public/c/system/system_export.h"
 #include "mojo/public/c/system/types.h"
 
 // |MojoCreateSharedBufferOptions|: Used to specify creation parameters for a
 // shared buffer to |MojoCreateSharedBuffer()|.
+//
 //   |uint32_t struct_size|: Set to the size of the
 //       |MojoCreateSharedBufferOptions| struct. (Used to allow for future
 //       extensions.)
+//
 //   |MojoCreateSharedBufferOptionsFlags flags|: Reserved for future use.
 //       |MOJO_CREATE_SHARED_BUFFER_OPTIONS_FLAG_NONE|: No flags; default mode.
-//
-// TODO(vtl): Maybe add a flag to indicate whether the memory should be
-// executable or not?
-// TODO(vtl): Also a flag for discardable (ashmem-style) buffers.
 
 typedef uint32_t MojoCreateSharedBufferOptionsFlags;
 
 #ifdef __cplusplus
 const MojoCreateSharedBufferOptionsFlags
     MOJO_CREATE_SHARED_BUFFER_OPTIONS_FLAG_NONE = 0;
 #else
 #define MOJO_CREATE_SHARED_BUFFER_OPTIONS_FLAG_NONE \
   ((MojoCreateSharedBufferOptionsFlags)0)
 #endif
 
 MOJO_STATIC_ASSERT(MOJO_ALIGNOF(int64_t) == 8, "int64_t has weird alignment");
 struct MOJO_ALIGNAS(8) MojoCreateSharedBufferOptions {
   uint32_t struct_size;
   MojoCreateSharedBufferOptionsFlags flags;
 };
 MOJO_STATIC_ASSERT(sizeof(MojoCreateSharedBufferOptions) == 8,
                    "MojoCreateSharedBufferOptions has wrong size");
 
 // |MojoDuplicateBufferHandleOptions|: Used to specify parameters in duplicating
 // access to a shared buffer to |MojoDuplicateBufferHandle()|.
+//
 //   |uint32_t struct_size|: Set to the size of the
 //       |MojoDuplicateBufferHandleOptions| struct. (Used to allow for future
 //       extensions.)
-//   |MojoDuplicateBufferHandleOptionsFlags flags|: Reserved for future use.
+//
+//   |MojoDuplicateBufferHandleOptionsFlags flags|: Flags to control the
+//       behavior of |MojoDuplicateBufferHandle()|. May be some combination of
+//       the following:
+//
 //       |MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE|: No flags; default
-//       mode.
+//           mode.
 //       |MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_READ_ONLY|: The duplicate
-//       shared buffer can only be mapped read-only. A read-only duplicate can
-//       only be created before the buffer is passed over a message pipe.
-//
-// TODO(vtl): Add flags to remove writability (and executability)? Also, COW?
+//           shared buffer can only be mapped read-only. A read-only duplicate
+//           may only be created before any handles to the buffer are passed
+//           over a message pipe.
 
 typedef uint32_t MojoDuplicateBufferHandleOptionsFlags;
 
 #ifdef __cplusplus
 const MojoDuplicateBufferHandleOptionsFlags
     MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE = 0;
 const MojoDuplicateBufferHandleOptionsFlags
     MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_READ_ONLY = 1 << 0;
 #else
 #define MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE \
@@ skipping 21 matching lines @@
 #endif
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 // Note: See the comment in functions.h about the meaning of the "optional"
 // label for pointer parameters.
 
 // Creates a buffer of size |num_bytes| bytes that can be shared between
-// applications (by duplicating the handle -- see |MojoDuplicateBufferHandle()|
-// -- and passing it over a message pipe). To access the buffer, one must call
-// |MojoMapBuffer()|.
+// processes. The returned handle may be duplicated any number of times by
+// |MojoDuplicateBufferHandle()|.
+//
+// To access the buffer's storage, one must call |MojoMapBuffer()|.
 //
 // |options| may be set to null for a shared buffer with the default options.
 //
 // On success, |*shared_buffer_handle| will be set to the handle for the shared
-// buffer. (On failure, it is not modified.)
-//
-// Note: While more than |num_bytes| bytes may apparently be
-// available/visible/readable/writable, trying to use those extra bytes is
-// undefined behavior.
+// buffer. On failure it is not modified.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
 //       |*options| is invalid).
 //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has
 //       been reached (e.g., if the requested size was too large, or if the
 //       maximum number of handles was exceeded).
 //   |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|.
 MOJO_SYSTEM_EXPORT MojoResult MojoCreateSharedBuffer(
     const struct MojoCreateSharedBufferOptions* options,  // Optional.
     uint64_t num_bytes,                                   // In.
     MojoHandle* shared_buffer_handle);                    // Out.
 
-// Duplicates the handle |buffer_handle| to a buffer. This creates another
-// handle (returned in |*new_buffer_handle| on success), which can then be sent
-// to another application over a message pipe, while retaining access to the
-// |buffer_handle| (and any mappings that it may have).
+// Duplicates the handle |buffer_handle| as a new shared buffer handle. On
+// success this returns the new handle in |*new_buffer_handle|. A shared buffer
+// remains allocated as long as there is at least one shared buffer handle
+// referencing it in at least one process in the system.
 //
 // |options| may be set to null to duplicate the buffer handle with the default
 // options.
 //
-// On success, |*shared_buffer_handle| will be set to the handle for the new
-// buffer handle. (On failure, it is not modified.)
-//
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
 //       |buffer_handle| is not a valid buffer handle or |*options| is invalid).
 //   |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|.
 MOJO_SYSTEM_EXPORT MojoResult MojoDuplicateBufferHandle(
     MojoHandle buffer_handle,
     const struct MojoDuplicateBufferHandleOptions* options,  // Optional.
     MojoHandle* new_buffer_handle);                          // Out.
 
 // Maps the part (at offset |offset| of length |num_bytes|) of the buffer given
 // by |buffer_handle| into memory, with options specified by |flags|. |offset +
 // num_bytes| must be less than or equal to the size of the buffer. On success,
-// |*buffer| points to memory with the requested part of the buffer. (On
-// failure, it is not modified.)
+// |*buffer| points to memory with the requested part of the buffer. On
+// failure |*buffer| it is not modified.
 //
-// A single buffer handle may have multiple active mappings (possibly depending
-// on the buffer type). The permissions (e.g., writable or executable) of the
-// returned memory may depend on the properties of the buffer and properties
-// attached to the buffer handle as well as |flags|.
+// A single buffer handle may have multiple active mappings The permissions
+// (e.g., writable or executable) of the returned memory depend on th
+// properties of the buffer and properties attached to the buffer handle, as
+// well as |flags|.
 //
-// Note: Though data outside the specified range may apparently be
-// available/visible/readable/writable, trying to use those extra bytes is
-// undefined behavior.
+// A mapped buffer must eventually be unmapped by calling |MojoUnmapBuffer()|
+// with the value of |*buffer| returned by this function.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
 //       |buffer_handle| is not a valid buffer handle or the range specified by
 //       |offset| and |num_bytes| is not valid).
 //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if the mapping operation itself failed
 //       (e.g., due to not having appropriate address space available).
 MOJO_SYSTEM_EXPORT MojoResult MojoMapBuffer(MojoHandle buffer_handle,
                                             uint64_t offset,
                                             uint64_t num_bytes,
                                             void** buffer,  // Out.
                                             MojoMapBufferFlags flags);
 
 // Unmaps a buffer pointer that was mapped by |MojoMapBuffer()|. |buffer| must
 // have been the result of |MojoMapBuffer()| (not some other pointer inside
-// the mapped memory), and the entire mapping will be removed (partial unmapping
-// is not supported). A mapping may only be unmapped once.
+// the mapped memory), and the entire mapping will be removed.
+//
+// A mapping may only be unmapped once.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if |buffer| is invalid (e.g., is not the
 //       result of |MojoMapBuffer()| or has already been unmapped).
 MOJO_SYSTEM_EXPORT MojoResult MojoUnmapBuffer(void* buffer);  // In.
 
 #ifdef __cplusplus
 }  // extern "C"
 #endif
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_BUFFER_H_