Updated documentation (added <code></code> and some other changes).

Review URL: http://codereview.chromium.org/9405009

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@122525 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 56 insertions, 42 deletions

diff --git a/ppapi/c/ppb_var_array_buffer.h b/ppapi/c/ppb_var_array_buffer.h
index c9c285f..06d6852 100644
--- a/ppapi/c/ppb_var_array_buffer.h
+++ b/ppapi/c/ppb_var_array_buffer.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From ppb_var_array_buffer.idl modified Thu Jan 26 14:50:50 2012. */
+/* From ppb_var_array_buffer.idl modified Thu Feb 16 14:06:44 2012. */
 
 #ifndef PPAPI_C_PPB_VAR_ARRAY_BUFFER_H_
 #define PPAPI_C_PPB_VAR_ARRAY_BUFFER_H_
@@ -18,7 +18,8 @@
 
 /**
  * @file
- * This file defines the <code>PPB_VarArrayBuffer</code> struct.
+ * This file defines the <code>PPB_VarArrayBuffer</code> struct providing
+ * a way to interact with JavaScript ArrayBuffers.
  */
 
 
@@ -27,68 +28,81 @@
  * @{
  */
 /**
- * PPB_VarArrayBuffer API. This provides a way to interact with JavaScript
- * ArrayBuffers, which represent a contiguous sequence of bytes. To manage the
- * reference count for a VarArrayBuffer, please see PPB_Var. Note that
- * these Vars are not part of the embedding page's DOM, and can only be shared
- * with JavaScript via pp::Instance's PostMessage and HandleMessage functions.
+ * The <code>PPB_VarArrayBuffer</code> interface provides a way to interact
+ * with JavaScript ArrayBuffers, which represent a contiguous sequence of
+ * bytes. Use <code>PPB_Var</code> to manage the reference count for a
+ * <code>VarArrayBuffer</code>. Note that these Vars are not part of the
+ * embedding page's DOM, and can only be shared with JavaScript using the
+ * <code>PostMessage</code> and <code>HandleMessage</code> functions of
+ * <code>pp::Instance</code>.
  */
 struct PPB_VarArrayBuffer_1_0 {
   /**
-   * Create a zero-initialized VarArrayBuffer.
+   * Create() creates a zero-initialized <code>VarArrayBuffer</code>.
    *
-   * @param[in] size_in_bytes The size of the ArrayBuffer that will be created.
+   * @param[in] size_in_bytes The size of the <code>ArrayBuffer</code> to
+   * be created.
    *
-   * @return A PP_Var which represents a VarArrayBuffer of the requested size
-   *         with a reference count of 1.
+   * @return A <code>PP_Var</code> representing a <code>VarArrayBuffer</code>
+   * of the requested size and with a reference count of 1.
    */
   struct PP_Var (*Create)(uint32_t size_in_bytes);
   /**
-   * Retrieves the length of the VarArrayBuffer in bytes. On success,
-   * byte_length is set to the length of the given ArrayBuffer var. On failure,
-   * byte_length is unchanged (this could happen, for instance, if the given
-   * PP_Var is not of type PP_VARTYPE_ARRAY_BUFFER). Note that ByteLength() will
-   * successfully retrieve the the size of an ArrayBuffer even if the
-   * ArrayBuffer is not currently mapped.
+   * ByteLength() retrieves the length of the <code>VarArrayBuffer</code> in
+   * bytes. On success, <code>byte_length</code> is set to the length of the
+   * given <code>ArrayBuffer</code> var. On failure, <code>byte_length</code>
+   * is unchanged (this could happen, for instance, if the given
+   * <code>PP_Var</code> is not of type <code>PP_VARTYPE_ARRAY_BUFFER</code>).
+   * Note that ByteLength() will successfully retrieve the size of an
+   * <code>ArrayBuffer</code> even if the <code>ArrayBuffer</code> is not
+   * currently mapped.
    *
-   * @param[in] array The ArrayBuffer whose length should be returned.
+   * @param[in] array The <code>ArrayBuffer</code> whose length should be
+   * returned.
    *
    * @param[out] byte_length A variable which is set to the length of the given
-   *             ArrayBuffer on success.
+   * <code>ArrayBuffer</code> on success.
    *
-   * @return PP_TRUE on success, PP_FALSE on failure.
+   * @return <code>PP_TRUE</code> on success, <code>PP_FALSE</code> on failure.
    */
   PP_Bool (*ByteLength)(struct PP_Var array, uint32_t* byte_length);
   /**
-   * Maps the ArrayBuffer in to the module's address space and returns a pointer
-   * to the beginning of the buffer for the given ArrayBuffer PP_Var. Note that
-   * calling Map() can be a relatively expensive operation. Use care when
-   * calling it in performance-critical code. For example, you should call it
-   * only once when looping over an ArrayBuffer:
+   * Map() maps the <code>ArrayBuffer</code> in to the module's address space
+   * and returns a pointer to the beginning of the buffer for the given
+   * <code>ArrayBuffer PP_Var</code>. Note that calling Map() can be a
+   * relatively expensive operation. Use care when calling it in
+   * performance-critical code. For example, you should call it only once when
+   * looping over an <code>ArrayBuffer</code>.
    *
-   * <code>
-   *   char* data = (char*)(array_buffer_if.Map(array_buffer_var));
-   *   uint32_t byte_length = 0;
-   *   PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length);
-   *   if (!ok)
-   *     return DoSomethingBecauseMyVarIsNotAnArrayBuffer();
-   *   for (uint32_t i = 0; i < byte_length; ++i)
-   *     data[i] = 'A';
-   * </code>
+   * <strong>Example:</strong>
    *
-   * @param[in] array The ArrayBuffer whose internal buffer should be returned.
+   * @code
+   * char* data = (char*)(array_buffer_if.Map(array_buffer_var));
+   * uint32_t byte_length = 0;
+   * PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length);
+   * if (!ok)
+   *   return DoSomethingBecauseMyVarIsNotAnArrayBuffer();
+   * for (uint32_t i = 0; i < byte_length; ++i)
+   *   data[i] = 'A';
+   * @endcode
    *
-   * @return A pointer to the internal buffer for this ArrayBuffer. Returns NULL
-   *         if the given PP_Var is not of type PP_VARTYPE_ARRAY_BUFFER.
+   * @param[in] array The <code>ArrayBuffer</code> whose internal buffer should
+   * be returned.
+   *
+   * @return A pointer to the internal buffer for this
+   * <code>ArrayBuffer</code>. Returns <code>NULL</code>
+   * if the given <code>PP_Var</code> is not of type
+   * <code>PP_VARTYPE_ARRAY_BUFFER</code>.
    */
   void* (*Map)(struct PP_Var array);
   /**
-   * Unmaps the given ArrayBuffer var from the module address space. Use this if
-   * you want to save memory but might want to Map the buffer again later. The
-   * PP_Var remains valid and should still be released using PPB_Var when you
-   * are done with the ArrayBuffer.
+   * Unmap() unmaps the given <code>ArrayBuffer</code> var from the module
+   * address space. Use this if you want to save memory but might want to call
+   * Map() to map the buffer again later. The <code>PP_Var</code> remains valid
+   * and should still be released using <code>PPB_Var</code> when you are done
+   * with the <code>ArrayBuffer</code>.
    *
-   * @param[in] array The ArrayBuffer which should be released.
+   * @param[in] array The <code>ArrayBuffer</code> to be released.
    */
   void (*Unmap)(struct PP_Var array);
 };