Updated descriptions to several functions, structs, enums

ppapi/c/pp_var.h

 /* Copyright (c) 2010 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
  * Defines the API ...
  */
 
 /**
  *
  * @addtogroup Enums
  * @{
  */
+
+/**
+ * PP_VarType is an enumeration of the different types that can be contained
+ * within a PP_VAR structure.
+ */
 typedef enum {
   PP_VARTYPE_UNDEFINED,
   PP_VARTYPE_NULL,
   PP_VARTYPE_BOOL,
   PP_VARTYPE_INT32,
   PP_VARTYPE_DOUBLE,
   PP_VARTYPE_STRING,
   PP_VARTYPE_OBJECT
 } PP_VarType;
 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_VarType, 4);
 /**
  * @}
  */
 
 /**
  * @addtogroup Structs
  * @{
  */
 
 /**
- * Do not rely on having a predictable and reproducible
- * int/double differentiation.
- * JavaScript has a "number" type for holding a number, and
- * does not differentiate between floating point and integer numbers. The
- * JavaScript library will try to optimize operations by using integers
- * when possible, but could end up with doubles depending on how the number
- * was arrived at.
+ * PP_VAR is a struct that represents a variant data type and can contain any

[Sang Ahn, 2011/02/01 19:19:00]

PP_VAR  does not represent a variant data type; it is a variant data type.  It
can't contain any data type, just the ones that are enumerated by PP_VarType.

[jond, 2011/02/02 16:54:51]

Fixed.

+ * value, such as a bool, int32, double, or string. This structure is for

[dmichael(do not use this one), 2011/02/01 22:17:22]

'int32' -> int32_t
'or string' -> 'string, or object.'
(I'm being a bit vague...  we might be able to say 'string, JavaScript object,
or a scriptable native object (see PPB_Class)'.  Not sure which is less
confusing.

Also...  it may not be good to say 'any value', since it is limited to a
particular set of types.  Maybe just get rid of 'any value, such as' so it just
says:
"...can contain a bool, int32_t, double, ..."

[jond, 2011/02/02 16:54:51]

It says this now:

"The PP_VAR struct is a variant data type and can contain any
 * value represented by the PP_VarType enum. "

On 2011/02/01 22:17:22, dmichael wrote:

+ * passing data between native code which can be strongly typed and the browser
+ * (JavaScript) which isn't strongly typed.
  *
- * Your best bet is to have a wrapper for variables
- * that always gets out the type you expect, converting as necessary.
+ * You cannot rely on having a predictable and reproducible int/double
+ * differentiation in JavaScript. JavaScript has a "number" type for holding
+ * a number, and does not differentiate between floating point and integer
+ * numbers. The JavaScript library will try to optimize operations by using

[Sang Ahn, 2011/02/01 19:19:00]

Javascript library -> Javascript operations
ie
"Javascript operations will try to optimize"

The phrase "Javascript library," tends to mean javascript code modules (e.g.
node.js)

[jond, 2011/02/02 16:54:51]

Fixed. 

On 2011/02/01 19:19:00, Sang Ahn wrote:

+ * integers when possible, but could end up with doubles.
  *
+ * PP_Var represents the best solution of using a wrapper for variables
+ * that always returns the type you expect (converting as necessary).

[dmichael(do not use this one), 2011/02/01 22:17:22]

I don't believe this is true.  PPB_Var has a function for converting, but you
have to do it manually.  A numeric PP_Var coming from JavaScript could be
int32_t or double, and the native code can't make assumptions.  That's what the
comment was trying to warn about.  pp::Var (the C++ wrapper) may do conversions
more automatically, but PP_Var does not and never will (I'm not sure how you'd
do it in C).

  */
 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.
    */
   int32_t padding;
 
@@ skipping 12 matching lines @@
 };
 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
+ */
 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
+ */
 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
+ */
 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.
+ * @param[in] value An int32
+ * @return A PP_Var 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.
+ * @param[in] value A double
+ * @return A PP_Var 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_ */