Minor tweaks to API documentation and code comments.

mojo/edk/system/core.h

 // Copyright 2013 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.
 
 #ifndef MOJO_EDK_SYSTEM_CORE_H_
 #define MOJO_EDK_SYSTEM_CORE_H_
 
 #include <stdint.h>
 
 #include "base/callback.h"
@@ skipping 46 matching lines @@
   MojoResult AsyncWait(MojoHandle handle,
                        MojoHandleSignals signals,
                        base::Callback<void(MojoResult)> callback);
 
   embedder::PlatformSupport* platform_support() const {
     return platform_support_.get();
   }
 
   // ---------------------------------------------------------------------------
 
-  // System calls implementation:
+  // The following methods are essentially implementations of the Mojo Core
+  // functions of the Mojo API, with the C interface translated to C++ by
+  // "mojo/edk/embedder/entrypoints.cc". The best way to understand the contract
+  // of these methods is to look at the header files defining the corresponding
+  // API functions, referenced below.
+
+  // These methods correspond to the API functions defined in
+  // "mojo/public/c/system/functions.h":
   MojoTimeTicks GetTimeTicksNow();
   MojoResult Close(MojoHandle handle);
   MojoResult Wait(MojoHandle handle,
                   MojoHandleSignals signals,
                   MojoDeadline deadline,
                   UserPointer<MojoHandleSignalsState> signals_state);
   MojoResult WaitMany(UserPointer<const MojoHandle> handles,
                       UserPointer<const MojoHandleSignals> signals,
                       uint32_t num_handles,
                       MojoDeadline deadline,
                       UserPointer<uint32_t> result_index,
                       UserPointer<MojoHandleSignalsState> signals_states);
+
+  // These methods correspond to the API functions defined in
+  // "mojo/public/c/system/message_pipe.h":
   MojoResult CreateMessagePipe(
       UserPointer<const MojoCreateMessagePipeOptions> options,
       UserPointer<MojoHandle> message_pipe_handle0,
       UserPointer<MojoHandle> message_pipe_handle1);
   MojoResult WriteMessage(MojoHandle message_pipe_handle,
                           UserPointer<const void> bytes,
                           uint32_t num_bytes,
                           UserPointer<const MojoHandle> handles,
                           uint32_t num_handles,
                           MojoWriteMessageFlags flags);
   MojoResult ReadMessage(MojoHandle message_pipe_handle,
                          UserPointer<void> bytes,
                          UserPointer<uint32_t> num_bytes,
                          UserPointer<MojoHandle> handles,
                          UserPointer<uint32_t> num_handles,
                          MojoReadMessageFlags flags);
+
+  // These methods correspond to the API functions defined in
+  // "mojo/public/c/system/data_pipe.h":
   MojoResult CreateDataPipe(
       UserPointer<const MojoCreateDataPipeOptions> options,
       UserPointer<MojoHandle> data_pipe_producer_handle,
       UserPointer<MojoHandle> data_pipe_consumer_handle);
   MojoResult WriteData(MojoHandle data_pipe_producer_handle,
                        UserPointer<const void> elements,
                        UserPointer<uint32_t> num_bytes,
                        MojoWriteDataFlags flags);
   MojoResult BeginWriteData(MojoHandle data_pipe_producer_handle,
                             UserPointer<void*> buffer,
                             UserPointer<uint32_t> buffer_num_bytes,
                             MojoWriteDataFlags flags);
   MojoResult EndWriteData(MojoHandle data_pipe_producer_handle,
                           uint32_t num_bytes_written);
   MojoResult ReadData(MojoHandle data_pipe_consumer_handle,
                       UserPointer<void> elements,
                       UserPointer<uint32_t> num_bytes,
                       MojoReadDataFlags flags);
   MojoResult BeginReadData(MojoHandle data_pipe_consumer_handle,
                            UserPointer<const void*> buffer,
                            UserPointer<uint32_t> buffer_num_bytes,
                            MojoReadDataFlags flags);
   MojoResult EndReadData(MojoHandle data_pipe_consumer_handle,
                          uint32_t num_bytes_read);
+
+  // These methods correspond to the API functions defined in
+  // "mojo/public/c/system/buffer.h":
   MojoResult CreateSharedBuffer(
       UserPointer<const MojoCreateSharedBufferOptions> options,
       uint64_t num_bytes,
       UserPointer<MojoHandle> shared_buffer_handle);
   MojoResult DuplicateBufferHandle(
       MojoHandle buffer_handle,
       UserPointer<const MojoDuplicateBufferHandleOptions> options,
       UserPointer<MojoHandle> new_buffer_handle);
   MojoResult MapBuffer(MojoHandle buffer_handle,
                        uint64_t offset,
@@ skipping 26 matching lines @@
   base::Lock mapping_table_lock_;  // Protects |mapping_table_|.
   MappingTable mapping_table_;
 
   DISALLOW_COPY_AND_ASSIGN(Core);
 };
 
 }  // namespace system
 }  // namespace mojo
 
 #endif  // MOJO_EDK_SYSTEM_CORE_H_