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

ppapi/c/ppb_core.h

Index: ppapi/c/ppb_core.h
===================================================================
--- ppapi/c/ppb_core.h	(revision 76386)
+++ ppapi/c/ppb_core.h	(working copy)
@@ -17,8 +17,9 @@
 
 /**
  * @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,48 +27,77 @@
  * @{
  */
 
-/** {PENDING: describe PPB_CORE} */
+/**
+ * The PPB_Core interface contains pointers to functions
+ * related to memory, thread, and time management on the browser.

[dmichael(do not use this one), 2011/03/02 15:15:26]

I would take 'management' out (or move it after memory, as you had above).  I
don't think 'time management' is what we mean.

[jond, 2011/03/02 17:11:12]

Done.

[jond, 2011/03/02 17:11:12]

Done.

+ *
+ */
 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 save to

[dmichael(do not use this one), 2011/03/02 15:15:26]

save->safe

[jond, 2011/03/02 17:11:12]

Done.

+   * 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

[dmichael(do not use this one), 2011/03/02 15:15:26]

'second argument as the' -> 'second argument to the'

[jond, 2011/03/02 17:11:12]

Done.

    * callback. Many applications won't need this, but it allows a plugin to
@@ -75,16 +105,24 @@
    *
    * 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 A int32_t delay in milliseconds.

[dmichael(do not use this one), 2011/03/02 15:15:26]

A->An

[jond, 2011/03/02 17:11:12]

Done.

+   * @param[in] callback A PP_CompletionCallback callback function that the
+   * browser calls when...

[dmichael(do not use this one), 2011/03/02 15:15:26]

Maybe:  "The PP_CompletionCallback callback function that the browser will call
after the specified delay."

[jond, 2011/03/02 17:11:12]

Done.

+   * @param[in] result An int32_t

[dmichael(do not use this one), 2011/03/02 15:15:26]

Maybe 'An int32_t that the browser will pass to the given
PP_CompletionCallback.'

[jond, 2011/03/02 17:11:12]

Done.

    */
   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 is useful for implementing sanity checks, and deciding if dispatching
-   * via CallOnMainThread() is required.
+   * This function useful for implementing sanity checks, and deciding if

[dmichael(do not use this one), 2011/03/02 15:15:26]

'function'->'function is'

[jond, 2011/03/02 17:11:12]

Done.

+   * dispatching using CallOnMainThread() is required.
+   *
+   * @return A PP_BOOL containing PP_TRUE if successful, otherwise PP_FALSE.

[dmichael(do not use this one), 2011/03/02 15:15:26]

'if successful,'->'if the current thread is the main pepper thread,'

[jond, 2011/03/02 17:11:12]

Done.

    */
   PP_Bool (*IsMainThread)();
 };