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

ppapi/api/ppb_var_array_buffer.idl

 /* Copyright (c) 2012 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 defines the <code>PPB_VarArrayBuffer</code> struct.
+ * This file defines the <code>PPB_VarArrayBuffer</code> struct providing.

[dmichael (off chromium), 2012/02/15 17:59:35]

nit: extra period.

[jond, 2012/02/16 21:23:51]

Done.

+ * a way to interact with JavaScript ArrayBuffers.
  */
 
 label Chrome {
   M18 = 1.0
 };
 
 /**
- * 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. Refer to <code>PPB_Var</code> to manage the reference count for a

[dmichael (off chromium), 2012/02/15 17:59:35]

Maybe "Use" instead of "Refer to"?

[jond, 2012/02/16 21:23:51]

Done.

+ * <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>.
  */
 [macro="PPB_VAR_ARRAY_BUFFER_INTERFACE"]
 interface PPB_VarArrayBuffer {
   /**
-   * 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.
    */
   PP_Var Create([in] 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 the size of an

[dmichael (off chromium), 2012/02/15 17:59:35]

extra "the"

[jond, 2012/02/16 21:23:51]

Done.

+   * <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([in] PP_Var array, [out] 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>
+   * <strong>Example:</strong>
+   *
+   * @code

[dmichael (off chromium), 2012/02/15 17:59:35]

<code>

[jond, 2012/02/16 21:23:51]

Actually, I've been asked to go back to @code @endcode, because you loose
formatting (spaces) with <code></code> when used for blocks of code.

On 2012/02/15 17:59:35, dmichael wrote:

    *   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>
+   * @endcode

[dmichael (off chromium), 2012/02/15 17:59:35]

</code>

[jond, 2012/02/16 21:23:51]

Actually, I've been asked to go back to @code @endcode, because you loose
formatting (spaces) with <code></code> when used for blocks of code.

[dmichael (off chromium), 2012/02/16 22:43:21]

Weird. I thought they worked the same. Okay.

    *
-   * @param[in] array The ArrayBuffer whose internal buffer should be returned.
+   * @param[in] array The <code>ArrayBuffer</code> whose internal buffer should
+   * be returned.
    *
-   * @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.
+   * @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>.
    */
   mem_t Map([in] 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([in] PP_Var array);
 };