Mostly minor changes such as adding <code></code> around elements, a little rewriting, and a few ...

ppapi/c/pp_var.h

-/* 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.
  */
 #ifndef PPAPI_C_PP_VAR_H_
 #define PPAPI_C_PP_VAR_H_
 
 #include "ppapi/c/pp_bool.h"
 #include "ppapi/c/pp_macros.h"
 #include "ppapi/c/pp_stdint.h"
 
 /**
  * @file
  * This file defines the API for handling the passing of data types between
  * your module and the page.
  */
 
 /**
  *
  * @addtogroup Enums
  * @{
  */
 
 /**
- * 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 {
   /**
    * An undefined value.
    */
   PP_VARTYPE_UNDEFINED,
 
   /**
    * 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.

[dmichael (off chromium), 2011/06/27 15:45:41]

I think this is one place where we could legitimately say 'Native Client
modules'.  I would also get rid of 'currently'; I don't think we'll ever add
support back in.

    */
   PP_VARTYPE_OBJECT,
 
   /**
    * 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
 } PP_VarType;
 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_VarType, 4);
 /**
  * @}
  */
 
 /**
  * @addtogroup Structs
  * @{
  */
 
 /**
- * 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.
+  /**
+   * This value ensures <code>value</code> is aligned on an 8-byte boundary

[dmichael (off chromium), 2011/06/27 15:45:41]

I think this says 'value' one too many times.  Maybe just say:
'<code>padding</code> ensures <code>value</code>...'

[jond, 2011/06/29 21:14:38]

Had to put "The <code>padding</code>" because padding is lower case and I
couldn't start the sentence with that.

On 2011/06/27 15:45:41, dmichael1 wrote:

+   * 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 value represents how you want to treat this PP_Var: as a bool, int,
+   * double, or id.

[dmichael (off chromium), 2011/06/27 15:45:41]

This comment is not accurate.  |value| really does contain the value for the
PP_Var; the type of the PP_Var is indicated by the field |type| above.  It's
more like:
"<code>value</code> represents the contents of the PP_Var. At most one of the
fields of <code>value</code> is valid at a time, based upon <code>type</code>."

[jond, 2011/06/29 21:14:38]

Done.

[jond, 2011/06/29 21:14:38]

Done.

+   */
   union {
+    /**
+     * This value indiciates that this <code>PP_Var</code> will be treatd as a
+     * bool.
+     */

[dmichael (off chromium), 2011/06/27 15:45:41]

Something like:
'If <code>type</code> is PP_VARTYPE_BOOL, <code>as_bool</code> represents the
value of this PP_Var as a PP_Bool.'

And similarly for the fields below.

[jond, 2011/06/29 21:14:38]

Can you double-check the as_id description now...

On 2011/06/27 15:45:41, dmichael1 wrote:

     PP_Bool as_bool;
+
+    /**
+     * This value indiciates that this <code>PP_Var</code> will be treatd as an
+     * int.
+     */
     int32_t as_int;
+
+    /**
+     * This value indiciates that this <code>PP_Var</code> will be treatd as a
+     * double.
+     */
     double as_double;
 
     /**
      * Internal ID for strings objects, arrays, and dictionaries. The

[dmichael (off chromium), 2011/06/27 15:45:41]

please add a comma after strings since you're in the neighborhood.

[jond, 2011/06/29 21:14:38]

Done.

-     * 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
+     * identifier is an opaque handle assigned by the browser to the module. It

[dmichael (off chromium), 2011/06/27 15:45:41]

I think we should just take out 'to the module'; I think it's slightly
confusing.

[jond, 2011/06/29 21:14:38]

Done.

[jond, 2011/06/29 21:14:38]

Done.

+     * 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;
 };
 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Var, 16);
 /**
  * @}
  */
 
 /**
  * @addtogroup Functions
  * @{
  */
 
 /**
- * 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
+ * This function 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} };
   return result;
 }
 
 /**
- * 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
+ * This function function is used to wrap a null value into a

[dmichael (off chromium), 2011/06/27 15:45:41]

If you stick with this wording, remove the extra 'function'

[jond, 2011/06/29 21:14:38]

Done.

+ * <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} };
   return result;
 }
 
 /**
- * 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
+ * This function isused to wrap a boolean value into a

[dmichael (off chromium), 2011/06/27 15:45:41]

isused->is used

[jond, 2011/06/29 21:14:38]

Done.

+ * <code>PP_VAR</code> struct for passing to the browser.
+ * @param[in] value A <code>PP_Bool</code> enumeration
+ * @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} };
   result.value.as_bool = value;
   return result;
 }
 
 /**
- * PP_MakeInt32() is a utility function used to wrap a 32 bit integer value
- * into a PP_VAR struct for passing to the browser.
+ * This function 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
- * @return A PP_Var structure
+ * @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} };
   result.value.as_int = value;
   return result;
 }
 
 /**
- * PP_MakeDouble() is a utility function used to wrap a double value into a
- * PP_VAR struct for passing to the browser.
+ * This function is used to wrap a double value into a
+ * <code>PP_VAR</code> struct for passing to the browser.
  * @param[in] value A double
- * @return A PP_Var structure
+ * @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} };
   result.value.as_double = value;
   return result;
 }
 /**
  * @}
  */
 
 #endif  /* PPAPI_C_PP_VAR_H_ */