Minor doc changes. Mostly commented out TODO and {PENDING notes that engineers had made.

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

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

5 files changed, 90 insertions, 43 deletions

diff --git a/ppapi/c/pp_input_event.h b/ppapi/c/pp_input_event.h
index d7a14b9..cb10932 100644
--- a/ppapi/c/pp_input_event.h
+++ b/ppapi/c/pp_input_event.h
@@ -115,9 +115,9 @@ struct PP_InputEvent_Key {
 
   /**
    * The key code.
-   *
-   * TODO(brettw) define what these actually are.
    */
+
+// TODO(brettw) define what these actually are.
   uint32_t key_code;
 };
 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Key, 8);
@@ -208,7 +208,7 @@ struct PP_InputEvent_Mouse {
    */
   float y;
 
-  /** TODO(brettw) figure out exactly what this means. */
+  // TODO(brettw) figure out exactly what this means.
   int32_t click_count;
 };
 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_InputEvent_Mouse, 20);
diff --git a/ppapi/c/ppb_class.h b/ppapi/c/ppb_class.h
index e2fc940..64c215b 100644
--- a/ppapi/c/ppb_class.h
+++ b/ppapi/c/ppb_class.h
@@ -15,7 +15,8 @@
 
 /**
  * @file
- * Defines the PPB_Class struct.
+ * This file defines the PPB_Class struct which is an interface for
+ * implementing JavaScript-accessible objects.
  *
  */
 
diff --git a/ppapi/c/ppb_core.h b/ppapi/c/ppb_core.h
index c577013..0bc7f9c 100644
--- a/ppapi/c/ppb_core.h
+++ b/ppapi/c/ppb_core.h
@@ -17,8 +17,9 @@ struct PP_CompletionCallback;
 
 /**
  * @file
- * Defines the API ...
- *
+ * This file defines the PPB_Core interface defined by the browser and
+ * and containing pointers to functions related to memory management,
+ * time, and threads.
  */
 
 /**
@@ -26,65 +27,104 @@ struct PP_CompletionCallback;
  * @{
  */
 
-/** {PENDING: describe PPB_CORE} */
+/**
+ * The PPB_Core interface contains pointers to functions related to memory
+ * management, time, and threads on the browser.
+ *
+ */
 struct PPB_Core {
-  /** Same as AddRefVar for Resources. */
+  /**
+   * Same as AddRefVar for Resources.
+   * AddRefResource is a pointer to a function that adds a reference to
+   * a resource.
+   *
+   * @param[in] config A PP_Resource containing the resource.
+   */
   void (*AddRefResource)(PP_Resource resource);
 
-  /** Same as ReleaseVar for Resources. */
+  /**
+   * ReleaseResource is a pointer to a function that removes a reference
+   * from a resource.
+   *
+   * @param[in] config A PP_Resource containing the resource.
+   */
+/*Same as ReleaseVar for Resources. */
   void (*ReleaseResource)(PP_Resource resource);
 
   /**
-   * Allocate memory.
+   * MemAlloc is a pointer to a function that allocate memory.
    *
-   * @return NULL If the allocation fails.
+   * @param[in] num_bytes A size_t number of bytes to allocate.
+   * @return A pointer to the memory if successful, NULL If the
+   * allocation fails.
    */
   void* (*MemAlloc)(size_t num_bytes);
 
-  /** Free memory; it's safe to pass NULL. */
+  /**
+   * MemFree is a pointer to a function that deallocates memory.
+   *
+   * @param[in] ptr A pointer to the memory to deallocate. It is safe to
+   * pass NULL to this function.
+   */
   void (*MemFree)(void* ptr);
 
   /**
-   * Returns the "wall clock time" according to the browser.
+   * GetTime is a pointer to a function that returns the "wall clock
+   * time" according to the browser.
    *
-   * See the definition of PP_Time.
+   * @return A PP_Time containing the "wall clock time" according to the
+   * browser.
    */
   PP_Time (*GetTime)();
 
   /**
-   * Returns the "tick time" according to the browser. This clock is used by
-   * the browser when passing some event times to the plugin (e.g., via the
+   * GetTimeTicks is a pointer to a function that returns the "tick time"
+   * according to the browser. This clock is used by the browser when passing
+   * some event times to the plugin (e.g., via the
    * PP_InputEvent::time_stamp_seconds field). It is not correlated to any
    * actual wall clock time (like GetTime()). Because of this, it will not run
    * change if the user changes their computer clock.
    *
-   * TODO(brettw) http://code.google.com/p/chromium/issues/detail?id=57448
-   * This currently does change with wall clock time, but will be fixed in
-   * a future release.
+   * @return A PP_TimeTicks containing the "tick time" according to the
+   * browser.
    */
+
+// TODO(brettw) http://code.google.com/p/chromium/issues/detail?id=57448
+// This currently does change with wall clock time, but will be fixed in
+// a future release.
   PP_TimeTicks (*GetTimeTicks)();
 
   /**
-   * Schedules work to be executed on the main plugin thread after the
-   * specified delay. The delay may be 0 to specify a call back as soon as
-   * possible.
+   * CallOnMainThread is a pointer to a function that schedules work to be
+   * executed on the main module thread after the specified delay. The delay
+   * may be 0 to specify a call back as soon as possible.
    *
-   * The |result| parameter will just be passed as the second argument as the
+   * The |result| parameter will just be passed as the second argument to the
    * callback. Many applications won't need this, but it allows a plugin to
    * emulate calls of some callbacks which do use this value.
    *
    * NOTE: If the browser is shutting down or if the plugin has no instances,
    * then the callback function may not be called.
+   *
+   * @param[in] delay_in_milliseconds An int32_t delay in milliseconds.
+   * @param[in] callback A PP_CompletionCallback callback function that the
+   * browser will call after the specified delay.
+   * @param[in] result An int32_t that the browser will pass to the given
+   * PP_CompletionCallback.
    */
   void (*CallOnMainThread)(int32_t delay_in_milliseconds,
                            struct PP_CompletionCallback callback,
                            int32_t result);
 
   /**
-   * Returns true if the current thread is the main pepper thread.
+   * IsMainThread is a pointer to a function that returns true if the
+   * current thread is the main pepper thread.
+   *
+   * This function is useful for implementing sanity checks, and deciding if
+   * dispatching using CallOnMainThread() is required.
    *
-   * This is useful for implementing sanity checks, and deciding if dispatching
-   * via CallOnMainThread() is required.
+   * @return A PP_BOOL containing PP_TRUE if the current thread is the main
+   * pepper thread, otherwise PP_FALSE.
    */
   PP_Bool (*IsMainThread)();
 };
diff --git a/ppapi/c/ppb_var.h b/ppapi/c/ppb_var.h
index 9d2a268..47096c6 100644
--- a/ppapi/c/ppb_var.h
+++ b/ppapi/c/ppb_var.h
@@ -17,7 +17,7 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PPB_Var struct.
  */
 
 /**
@@ -27,11 +27,10 @@
  */
 
 /**
- * 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,
@@ -100,10 +99,11 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_ObjectProperty, 72);
  * 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,
@@ -170,8 +170,6 @@ struct PPB_Var {
    * 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
@@ -180,6 +178,9 @@ struct PPB_Var {
    * (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);
@@ -188,11 +189,12 @@ struct PPB_Var {
    * 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);
@@ -201,11 +203,12 @@ struct PPB_Var {
    * 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);
@@ -216,11 +219,12 @@ struct PPB_Var {
    * 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);
@@ -230,8 +234,6 @@ struct PPB_Var {
    * 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
@@ -258,6 +260,9 @@ struct PPB_Var {
    *     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,
diff --git a/ppapi/c/ppp.h b/ppapi/c/ppp.h
index ed1b4c3..2a8f182 100644
--- a/ppapi/c/ppp.h
+++ b/ppapi/c/ppp.h
@@ -19,10 +19,11 @@
  * @file
  * This file defines three functions that your module must
  * implement to interact with the browser.
- *
- * {PENDING: undefine PP_EXPORT?}
  */
 
+// {PENDING: undefine PP_EXPORT?}
+
+
 /* We don't want name mangling for these external functions.  We only need
  * 'extern "C"' if we're compiling with a C++ compiler.
  */