Minor doc changes. Mostly commented out TODO and {PENDING notes that engineer...

ppapi/c/ppb_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_PPB_VAR_H_
 #define PPAPI_C_PPB_VAR_H_
 
 #include "ppapi/c/pp_bool.h"
 #include "ppapi/c/pp_instance.h"
 #include "ppapi/c/pp_macros.h"
 #include "ppapi/c/pp_module.h"
 #include "ppapi/c/pp_resource.h"
 #include "ppapi/c/pp_stdint.h"
 #include "ppapi/c/pp_var.h"
 
 #define PPB_VAR_INTERFACE "PPB_Var;0.4"
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PPB_Var struct.
  */
 
 /**
  *
  * @addtogroup Enums
  * @{
  */
 
 /**
- * Defines the PPB_Var struct.
  * See http://code.google.com/p/ppapi/wiki/InterfacingWithJavaScript
  * for general information on using this interface.
- * {PENDING: Should the generated doc really be pointing to methods?}
  */
+// PENDING: Should the generated doc really be pointing to methods?
 enum PP_ObjectProperty_Modifier {
   PP_OBJECTPROPERTY_MODIFIER_NONE       = 0,
   PP_OBJECTPROPERTY_MODIFIER_READONLY   = 1 << 0,
   PP_OBJECTPROPERTY_MODIFIER_DONTENUM   = 1 << 1,
   PP_OBJECTPROPERTY_MODIFIER_DONTDELETE = 1 << 2,
   PP_OBJECTPROPERTY_MODIFIER_HASVALUE   = 1 << 3
 };
 PP_COMPILE_ASSERT_ENUM_SIZE_IN_BYTES(PP_ObjectProperty_Modifier, 4);
 /**
  * @}
@@ skipping 48 matching lines @@
  *
  * Make sure not to intermix non-JS with JS calls when relying on this behavior
  * to catch JS exceptions, as non-JS functions will still execute!
 
  * JS engine's exceptions will always be of type PP_VARTYPE_OBJECT. However,
  * PP_Var interface can also throw PP_VARTYPE_STRING exceptions, in situations
  * where there's no JS execution context defined. These are usually invalid
  * parameter errors - passing an invalid PP_Var value, for example, will always
  * result in an PP_VARTYPE_STRING exception. Exceptions will not be of any other
  * type.
- * TODO(neb): Specify the exception for ill-formed PP_Vars, invalid module,
- * instance, resource, string and object ids.
  *
  */
+
+// TODO(neb): Specify the exception for ill-formed PP_Vars, invalid module,
+// instance, resource, string and object ids.
 struct PPB_Var {
   /**
    * Adds a reference to the given var. If this is not a refcounted object,
    * this function will do nothing so you can always call it no matter what the
    * type.
    */
   void (*AddRef)(struct PP_Var var);
 
   /**
    * Removes a reference to given var, deleting it if the internal refcount
@@ skipping 46 matching lines @@
    */
   struct PP_Var (*ConvertType)(PP_Instance instance,
                                struct PP_Var var,
                                PP_VarType new_type,
                                struct PP_Var* exception);
 
   /**
    * Sets a property on the object, similar to Object.prototype.defineProperty.
    *
    * First, if object is not PP_VARTYPE_OBJECT, throw an exception.
-   * TODO(neb): Specify the exception. Ideally, it would be a TypeError, but
-   * don't have the JS context to create new objects, we might throw a string.
    * Then, the property's 'name' field is converted to string using
    * ConvertType (ToString [9.8]).
    * After that, defineOwnProperty [8.12.9, 15.4.5.1] is called with the
    * property.
    * To set a simple property, set the value and set modifiers to default
    * (Writable|Enumerable|Configurable|HasValue), see [8.12.15] and
    * function PPB_MakeSimpleProperty.
    */
+
+// TODO(neb): Specify the exception. Ideally, it would be a TypeError, but
+// don't have the JS context to create new objects, we might throw a string.
   void (*DefineProperty)(struct PP_Var object,
                          struct PP_ObjectProperty property,
                          struct PP_Var* exception);
 
   /**
    * Tests whether an object has a property with a given name.
    *
    * First, if object is not PP_VARTYPE_OBJECT, throw an exception.
-   * TODO(neb): Specify the exception. Ideally, it would be a TypeError, but
-   * don't have the JS context to create new objects, we might throw a string.
    * Then, convert 'property' to string using ConvertType (ToString [9.8]).
    * Then return true if the given property exists on the object [8.12.6].
    */
+
+// TODO(neb): Specify the exception. Ideally, it would be a TypeError, but
+// don't have the JS context to create new objects, we might throw a string.
   PP_Bool (*HasProperty)(struct PP_Var object,
                          struct PP_Var property,
                          struct PP_Var* exception);
 
   /**
    * Returns a given property of the object.
    *
    * First, if object is not PP_VARTYPE_OBJECT, throw an exception.
-   * TODO(neb): Specify the exception. Ideally, it would be a TypeError, but
-   * don't have the JS context to create new objects, we might throw a string.
    * Then, convert 'property' to string using ConvertType (ToString [9.8]).
    * Then return the given property of the object [8.12.2].
    */
+
+// TODO(neb): Specify the exception. Ideally, it would be a TypeError, but
+// don't have the JS context to create new objects, we might throw a string.
   struct PP_Var (*GetProperty)(struct PP_Var object,
                                struct PP_Var property,
                                struct PP_Var* exception);
 
   /**
    * Delete a property from the object, return true if succeeded.
    *
    * True is returned if the property didn't exist in the first place.
    *
    * First, if object is not PP_VARTYPE_OBJECT, throw an exception.
-   * TODO(neb): Specify the exception. Ideally, it would be a TypeError, but
-   * don't have the JS context to create new objects, we might throw a string.
    * Then, convert 'property' to string using ConvertType (ToString [9.8]).
    * Then delete the given property of the object [8.12.7].
    */
+
+// TODO(neb): Specify the exception. Ideally, it would be a TypeError, but
+// don't have the JS context to create new objects, we might throw a string.
   PP_Bool (*DeleteProperty)(struct PP_Var object,
                             struct PP_Var property,
                             struct PP_Var* exception);
 
   /**
    * Retrieves all property names on the given object. Property names include
    * methods.
    *
    * If object is not PP_VARTYPE_OBJECT, throw an exception.
-   * TODO(neb): Specify the exception. Ideally, it would be a TypeError, but
-   * don't have the JS context to create new objects, we might throw a string.
    *
    * If there is a failure, the given exception will be set (if it is non-NULL).
    * On failure, |*properties| will be set to NULL and |*property_count| will be
    * set to 0.
    *
    * A pointer to the array of property names will be placed in |*properties|.
    * The caller is responsible for calling Release() on each of these properties
    * (as per normal refcounted memory management) as well as freeing the array
    * pointer with PPB_Core.MemFree().
    *
    * This function returns all "enumerable" properties. Some JavaScript
    * properties are "hidden" and these properties won't be retrieved by this
    * function, yet you can still set and get them. You can use JS
    * Object.getOwnPropertyNames() to access these properties.
    *
    * Example:
    * <pre>  uint32_t count;
    *   PP_Var* properties;
    *   ppb_var.EnumerateProperties(object, &count, &properties);
    *
    *   ...use the properties here...
    *
    *   for (uint32_t i = 0; i < count; i++)
    *     ppb_var.Release(properties[i]);
    *   ppb_core.MemFree(properties); </pre>
    */
+
+// TODO(neb): Specify the exception. Ideally, it would be a TypeError, but
+// don't have the JS context to create new objects, we might throw a string.
   void (*EnumerateProperties)(struct PP_Var object,
                               uint32_t* property_count,
                               struct PP_Var** properties,
                               struct PP_Var* exception);
 
   /**
    * Check if an object is a JS Function [9.11].
    */
   PP_Bool (*IsCallable)(struct PP_Var object);
 
@@ skipping 58 matching lines @@
   result.setter = PP_MakeUndefined();
   result.modifiers = PP_OBJECTPROPERTY_MODIFIER_HASVALUE;
   return result;
 }
 /**
  * @}
  */
 
 #endif  /* PPAPI_C_PPB_VAR_H_ */