Index: ppapi/c/pp_var.h |
=================================================================== |
--- ppapi/c/pp_var.h (revision 90368) |
+++ ppapi/c/pp_var.h (working copy) |
@@ -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 @@ |
/** |
* 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 legitimat
|
*/ |
PP_VARTYPE_OBJECT, |
@@ -69,7 +70,7 @@ |
* 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,37 +86,56 @@ |
*/ |
/** |
- * 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. May
jond
2011/06/29 21:14:38
Had to put "The <code>padding</code>" because padd
|
+ * 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
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_VARTYP
jond
2011/06/29 21:14:38
Can you double-check the as_id description now...
|
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 t
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
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; |
@@ -132,9 +152,9 @@ |
*/ |
/** |
- * 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} }; |
@@ -142,9 +162,9 @@ |
} |
/** |
- * 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 '
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} }; |
@@ -152,10 +172,10 @@ |
} |
/** |
- * 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} }; |
@@ -164,10 +184,10 @@ |
} |
/** |
- * 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} }; |
@@ -176,10 +196,10 @@ |
} |
/** |
- * 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} }; |