Mostly minor changes such as adding <code></code> around elements, a little rewriting, and a few new documentation bits to pp_var.h. Mostly trying to ensure consistency across all docs and doing cleanup.

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

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

1 files changed, 79 insertions, 42 deletions

diff --git a/ppapi/c/pp_var.h b/ppapi/c/pp_var.h
index a15edef2..ad465f0 100644
--- a/ppapi/c/pp_var.h
+++ b/ppapi/c/pp_var.h
@@ -1,4 +1,4 @@
-/* Copyright (c) 2010 The Chromium Authors. All rights reserved.
+/* Copyright (c) 2011 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.
  */
@@ -22,8 +22,8 @@
  */
 
 /**
- * PP_VarType is an enumeration of the different types that can be contained
- * within a PP_VAR structure.
+ * The <code>PP_VarType</code> is an enumeration of the different types that
+ * can be contained within a <code>PP_Var</code> structure.
  */
 typedef enum {
   /**
@@ -33,35 +33,36 @@ typedef enum {
 
   /**
    * A NULL value. This is similar to undefined, but JavaScript differentiates
-   * the two so we expose it here as well.
+   * the two so it is exposed here as well.
    */
   PP_VARTYPE_NULL,
 
   /**
-   * A boolean value, use the as_bool member of the var.
+   * A boolean value, use the <code>as_bool</code> member of the var.
    */
   PP_VARTYPE_BOOL,
 
   /**
-   * A 32-bit integer value. Use the as_int member of the var.
+   * A 32-bit integer value. Use the <code>as_int</code> member of the var.
    */
   PP_VARTYPE_INT32,
 
   /**
-   * A double-precision floating point value. Use the as_double member of the
-   * var.
+   * A double-precision floating point value. Use the <code>as_double</code>
+   * member of the var.
    */
   PP_VARTYPE_DOUBLE,
 
   /**
-   * The Var represents a string. The as_id field is used to identify the
-   * string, which may be created and retrieved from the PPB_Var interface.
+   * The Var represents a string. The <code>as_id</code> field is used to
+   * identify the string, which may be created and retrieved from the
+   * <code>PPB_Var</code> interface.
    */
   PP_VARTYPE_STRING,
 
   /**
    * Represents a JavaScript object. This vartype is not currently usable
-   * from plugins, although it is used internally for some tasks.
+   * from modules, although it is used internally for some tasks.
    */
   PP_VARTYPE_OBJECT,
 
@@ -69,7 +70,7 @@ typedef enum {
    * Arrays and dictionaries are not currently supported but will be added
    * in future revisions. These objects are reference counted so be sure
    * to properly AddRef/Release them as you would with strings to ensure your
-   * plugin will continue to work with future versions of the API.
+   * module will continue to work with future versions of the API.
    */
   PP_VARTYPE_ARRAY,
   PP_VARTYPE_DICTIONARY
@@ -85,38 +86,65 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_VarType, 4);
  */
 
 /**
- * The PP_VAR struct is a variant data type and can contain any
- * value of one of the types named in the PP_VarType enum. This structure is
- * for passing data between native code which can be strongly typed and the
- * browser (JavaScript) which isn't strongly typed.
+ * The <code>PP_VAR</code> struct is a variant data type and can contain any
+ * value of one of the types named in the <code>PP_VarType</code> enum. This
+ * structure is for passing data between native code which can be strongly
+ * typed and the browser (JavaScript) which isn't strongly typed.
  *
  * JavaScript has a "number" type for holding a number, and does not
  * differentiate between floating point and integer numbers. The
  * JavaScript operations will try to optimize operations by using
  * integers when possible, but could end up with doubles. Therefore,
- * you can't assume a numeric PP_Var will be the type you expect.
+ * you can't assume a numeric <code>PP_Var</code> will be the type you expect.
  * Your code should be capable of handling either int32_t or double for numeric
  * PP_Vars sent from JavaScript.
  */
 struct PP_Var {
   PP_VarType type;
 
-  /** Ensures @a value is aligned on an 8-byte boundary relative to the
-   *  start of the struct. Some compilers align doubles on 8-byte boundaries
-   *  for 32-bit x86, and some align on 4-byte boundaries.
+  /**
+   * The <code>padding</code> ensures <code>value</code> is aligned on an
+   * 8-byte boundary relative to the start of the struct. Some compilers
+   * align doubles on 8-byte boundaries for 32-bit x86, and some align on
+   * 4-byte boundaries.
    */
   int32_t padding;
 
+  /**
+   * This <code>value</code> represents the contents of the PP_Var. Only one of
+   * the fields of <code>value</code> is valid at a time based upon
+   * <code>type</code>.
+   */
   union {
+    /**
+     * If <code>type</code> is <code>PP_VARTYPE_BOOL</code>,
+     * <code>as_bool</code> represents the value of this <code>PP_Var</code> as
+     * <code>PP_Bool</code>.
+     */
     PP_Bool as_bool;
+
+    /**
+     * If <code>type</code> is <code>PP_VARTYPE_INT32</code>,
+     * <code>as_int</code> represents the value of this <code>PP_Var</code> as
+     * <code>int32_t</code>.
+     */
     int32_t as_int;
+
+    /**
+     * If <code>type</code> is <code>PP_VARTYPE_DOUBLE</code>,
+     * <code>as_double</code> represents the value of this <code>PP_Var</code>
+     * as <code>double</code>.
+     */
     double as_double;
 
     /**
-     * Internal ID for strings objects, arrays, and dictionaries. The
-     * identifier is an opaque handle assigned by the browser to the plugin. It
-     * is guaranteed never to be 0, so a plugin can initialize this ID to 0 to
-     * indicate a "NULL handle."
+     * If <code>type</code> is <code>PP_VARTYPE_STRING</code>,
+     * <code>PP_VARTYPE_OBJECT</code>, <code>PP_VARTYPE_ARRAY</code>, or
+     * <code>PP_VARTYPE_DICTIONARY</code>,
+     * <code>as_id</code> represents the value of this <code>PP_Var</code> as
+     * an opaque handle assigned by the browser. This handle is guaranteed
+     * never to be 0, so a module can initialize this ID to 0 to indicate a
+     * "NULL handle."
      */
     int64_t as_id;
   } value;
@@ -132,9 +160,10 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Var, 16);
  */
 
 /**
- * PP_MakeUndefined() is a utility function used to wrap an undefined value
- * into a PP_VAR struct for passing to the browser.
- * @return A PP_Var structure
+ * PP_MakeUndefined() is used to wrap an undefined value into a
+ * <code>PP_Var</code> struct for passing to the browser.
+ *
+ * @return A <code>PP_Var</code> structure.
  */
 PP_INLINE struct PP_Var PP_MakeUndefined() {
   struct PP_Var result = { PP_VARTYPE_UNDEFINED, 0, {PP_FALSE} };
@@ -142,9 +171,10 @@ PP_INLINE struct PP_Var PP_MakeUndefined() {
 }
 
 /**
- * PP_MakeNull() is a utility function used to wrap a null value into a
- * PP_VAR struct for passing to the browser.
- * @return A PP_Var structure
+ * PP_MakeNull() is used to wrap a null value into a
+ * <code>PP_Var</code> struct for passing to the browser.
+ *
+ * @return A <code>PP_Var</code> structure,
  */
 PP_INLINE struct PP_Var PP_MakeNull() {
   struct PP_Var result = { PP_VARTYPE_NULL, 0, {PP_FALSE} };
@@ -152,10 +182,13 @@ PP_INLINE struct PP_Var PP_MakeNull() {
 }
 
 /**
- * PP_MakeBool() is a utility function used to wrap a boolean value into a
- * PP_VAR struct for passing to the browser.
- * @param[in] value A PP_Bool enumeration
- * @return A PP_Var structure
+ * PP_MakeBool() is used to wrap a boolean value into a
+ * <code>PP_Var</code> struct for passing to the browser.
+ *
+ * @param[in] value A <code>PP_Bool</code> enumeration to
+ * wrap.
+ *
+ * @return A <code>PP_Var</code> structure.
  */
 PP_INLINE struct PP_Var PP_MakeBool(PP_Bool value) {
   struct PP_Var result = { PP_VARTYPE_BOOL, 0, {PP_FALSE} };
@@ -164,10 +197,12 @@ PP_INLINE struct PP_Var PP_MakeBool(PP_Bool value) {
 }
 
 /**
- * PP_MakeInt32() is a utility function used to wrap a 32 bit integer value
- * into a PP_VAR struct for passing to the browser.
- * @param[in] value An int32
- * @return A PP_Var structure
+ * PP_MakeInt32() is used to wrap a 32 bit integer value
+ * into a <code>PP_Var</code> struct for passing to the browser.
+ *
+ * @param[in] value An int32 to wrap.
+ *
+ * @return A <code>PP_Var</code> structure.
  */
 PP_INLINE struct PP_Var PP_MakeInt32(int32_t value) {
   struct PP_Var result = { PP_VARTYPE_INT32, 0, {PP_FALSE} };
@@ -176,10 +211,12 @@ PP_INLINE struct PP_Var PP_MakeInt32(int32_t value) {
 }
 
 /**
- * PP_MakeDouble() is a utility function used to wrap a double value into a
- * PP_VAR struct for passing to the browser.
- * @param[in] value A double
- * @return A PP_Var structure
+ * PP_MakeDouble() is used to wrap a double value into a
+ * <code>PP_Var</code> struct for passing to the browser.
+ *
+ * @param[in] value A double to wrap.
+ *
+ * @return A <code>PP_Var</code> structure.
  */
 PP_INLINE struct PP_Var PP_MakeDouble(double value) {
   struct PP_Var result = { PP_VARTYPE_DOUBLE, 0, {PP_FALSE} };