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

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

8 files changed, 124 insertions, 52 deletions

diff --git a/ppapi/c/pp_bool.h b/ppapi/c/pp_bool.h
index dcc3923..d53fa00 100644
--- a/ppapi/c/pp_bool.h
+++ b/ppapi/c/pp_bool.h
@@ -9,7 +9,7 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PP_Bool enumeration for use in PPAPI C headers.
  */
 
 /**
@@ -19,10 +19,10 @@
  */
 
 /**
- * A boolean value for use in PPAPI C headers.  The standard bool type is not
- * available to pre-C99 compilers, and is not guaranteed to be compatible
- * between C and C++, whereas the PPAPI C headers can be included from C or C++
- * code.
+ * The PP_Bool enum is a boolean value for use in PPAPI C headers.  The
+ * standard bool type is not available to pre-C99 compilers, and is not
+ * guaranteed to be compatible between C and C++, whereas the PPAPI C
+ * headers can be included from C or C++ code.
  */
 typedef enum {
   PP_FALSE = 0,
@@ -33,9 +33,5 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_Bool, 4);
  * @}
  */
 
-
-
-
-
 #endif  /* PPAPI_C_PP_BOOL_H_ */
 
diff --git a/ppapi/c/pp_errors.h b/ppapi/c/pp_errors.h
index 0138f2f..36911b2 100644
--- a/ppapi/c/pp_errors.h
+++ b/ppapi/c/pp_errors.h
@@ -7,8 +7,7 @@
 
 /**
  * @file
- * Defines the API ...
-
+ * This file defines an enumeration of all Native Client errors.
  */
 
 /**
@@ -17,67 +16,77 @@
  * @{
  */
 
-/** Errors are negative valued. */
+/** This enumeration contains enumerators of all Native Client errors.
+ * Errors are negative valued.
+ */
 enum {
   PP_OK = 0,
 
   /**
-   * Returned by a function, taking a PP_CompletionCallback, that cannot
-   * complete synchronously.  This return value indicates that the given
+   * This value is returned by a function that accepts a PP_CompletionCallback
+   * and cannot complete synchronously.  This error indicates that the given
    * callback will be asynchronously notified of the final result once it is
    * available.
    */
   PP_ERROR_WOULDBLOCK = -1,
 
-  /** Indicates failure for unspecified reasons. */
+  /** This value indicates failure for unspecified reasons. */
   PP_ERROR_FAILED = -2,
 
   /**
-   * Indicates failure due to an asynchronous operation being interrupted,
-   * typically as a result of user action.
+   * This value indicates failure due to an asynchronous operation being
+   * interrupted, typically as a result of user action.
    */
   PP_ERROR_ABORTED = -3,
 
-  /** Indicates failure due to an invalid argument. */
+  /** This value indicates failure due to an invalid argument. */
   PP_ERROR_BADARGUMENT = -4,
 
-  /** Indicates failure due to an invalid PP_Resource. */
+  /** This value indicates failure due to an invalid PP_Resource. */
   PP_ERROR_BADRESOURCE = -5,
 
-  /** Indicates failure due to an unavailable PPAPI interface. */
+  /** This value indicates failure due to an unavailable PPAPI interface. */
   PP_ERROR_NOINTERFACE = -6,
 
-  /** Indicates failure due to insufficient privileges. */
+  /** This value indicates failure due to insufficient privileges. */
   PP_ERROR_NOACCESS = -7,
 
-  /** Indicates failure due to insufficient memory. */
+  /** This value indicates failure due to insufficient memory. */
   PP_ERROR_NOMEMORY = -8,
 
-  /** Indicates failure due to insufficient storage space. */
+  /** This value indicates failure due to insufficient storage space. */
   PP_ERROR_NOSPACE = -9,
 
-  /** Indicates failure due to insufficient storage quota. */
+  /** This value indicates failure due to insufficient storage quota. */
   PP_ERROR_NOQUOTA = -10,
 
-  /** Indicates failure due to an action already being in progress. */
+  /**
+   * This value indicates failure due to an action already being in
+   * progress.
+   */
   PP_ERROR_INPROGRESS = -11,
 
-  /** Indicates failure due to a file that does not exist. */
+  /** This value indicates failure due to a file that does not exist. */
   PP_ERROR_FILENOTFOUND = -20,
 
-  /** Indicates failure due to a file that already exists. */
+  /** This value indicates failure due to a file that already exists. */
   PP_ERROR_FILEEXISTS = -21,
 
-  /** Indicates failure due to a file that is too big. */
+  /** This value indicates failure due to a file that is too big. */
   PP_ERROR_FILETOOBIG = -22,
 
-  /** Indicates failure due to a file having been modified unexpectedly. */
+  /**
+   * This value indicates failure due to a file having been modified
+   * unexpectedly.
+   */
   PP_ERROR_FILECHANGED = -23,
 
-  /** Indicates failure due to a time limit being exceeded. */
+  /** This value indicates failure due to a time limit being exceeded. */
   PP_ERROR_TIMEDOUT = -30,
 
-  /** Indicates that the user cancelled rather providing expected input. */
+  /** This value indicates that the user cancelled rather than providing
+   * expected input.
+   */
   PP_ERROR_USERCANCEL = -40
 };
 
@@ -87,3 +96,4 @@ enum {
  */
 
 #endif  /* PPAPI_C_PP_ERRORS_H_ */
+
diff --git a/ppapi/c/pp_instance.h b/ppapi/c/pp_instance.h
index 9dcdc4b..500df2b 100644
--- a/ppapi/c/pp_instance.h
+++ b/ppapi/c/pp_instance.h
@@ -7,7 +7,8 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PP_Instance type which uniquely identifies one module
+ * instance.
  */
 
 #include "ppapi/c/pp_macros.h"
@@ -18,12 +19,13 @@
  * @{
  */
 
-/** A PP_Instance uniquely identifies one plugin instance, which is one time
- * that a page says \<embed>. There can be multiple instances of the same plugin
- * type on a page that will all be in the same module.
+/**
+ * The PP_Instance value uniquely identifies one instance of a module
+ * (.nexe/PP_Module). There will be one module instance for every
+ * \<embed> tag on a page.
  *
- * The identifier is an opaque handle assigned by the browser to the plugin. It
- * is guaranteed never to be 0, so a plugin can initialize it to 0 to
+ * This identifier is an opaque handle assigned by the browser to the module. It
+ * is guaranteed never to be 0, so a module can initialize it to 0 to
  * indicate a "NULL handle."
  */
 typedef int32_t PP_Instance;
diff --git a/ppapi/c/pp_module.h b/ppapi/c/pp_module.h
index 90126c4..ffd24a5 100644
--- a/ppapi/c/pp_module.h
+++ b/ppapi/c/pp_module.h
@@ -7,7 +7,8 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PP_Module type which uniquely identifies the module
+ * or .nexe.
  */
 
 #include "ppapi/c/pp_macros.h"
@@ -20,9 +21,11 @@
  */
 
 /**
- * A module uniquely identifies one plugin library. The identifier is an opaque
- * handle assigned by the browser to the plugin. It is guaranteed never to be
- * 0, so a plugin can initialize it to 0 to indicate a "NULL handle."
+ * The PP_Module value uniquely identifies the module or .nexe.
+ *
+ * This identifier is an opaque handle assigned by the browser to the module. It
+ * is guaranteed never to be 0, so a module can initialize it to 0 to
+ * indicate a "NULL handle."
  */
 typedef int32_t PP_Module;
 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_Module, 4);
diff --git a/ppapi/c/pp_point.h b/ppapi/c/pp_point.h
index 8ff052e..88ad670 100644
--- a/ppapi/c/pp_point.h
+++ b/ppapi/c/pp_point.h
@@ -7,7 +7,8 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the API to create a 2 dimensional point.
+ * 0,0 is the upper-left starting coordinate.
  */
 
 #include "ppapi/c/pp_macros.h"
@@ -18,8 +19,21 @@
  * @addtogroup Structs
  * @{
  */
+
+/**
+ * The PP_Point structure defines the x and y coordinates of a point.
+ */
 struct PP_Point {
+  /**
+   * This value represents the horizontal coordinate of a point, starting with 0
+   * as the left-most coordinate.
+   */
   int32_t x;
+
+  /**
+   * This value represents the vertical coordinate of a point, starting with 0
+   * as the top-most coordinate.
+   */
   int32_t y;
 };
 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Point, 8);
@@ -31,6 +45,16 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Point, 8);
  * @addtogroup Functions
  * @{
  */
+
+/**
+ * PP_MakePoint() creates a PP_Point given the x and y coordinates as int32_t
+ * values.
+ * @param[in] x An int32_t value representing a horizontal coordinate of a
+ * point, starting with 0 as the left-most coordinate.
+ * @param[in] y An int32_t value representing a vertical coordinate of a point,
+ * starting with 0 as the top-most coordinate.
+ * @return A PP_Point structure.
+ */
 PP_INLINE struct PP_Point PP_MakePoint(int32_t x, int32_t y) {
   struct PP_Point ret;
   ret.x = x;
diff --git a/ppapi/c/pp_rect.h b/ppapi/c/pp_rect.h
index 3debabb..3d79714 100644
--- a/ppapi/c/pp_rect.h
+++ b/ppapi/c/pp_rect.h
@@ -7,7 +7,7 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the APIs for creating a 2 dimensional rectangle.
  */
 
 #include "ppapi/c/pp_macros.h"
@@ -19,8 +19,19 @@
  * @addtogroup Structs
  * @{
  */
+
+/**
+ * The PP_Rect struct contains the size and location of a 2D rectangle.
+ */
 struct PP_Rect {
+
+  /**
+   * This value represents the x and y coordinates of the upper-left corner of
+   * the rectangle.
+   */
   struct PP_Point point;
+
+  /** This value represents the width and height of the rectangle. */
   struct PP_Size size;
 };
 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Rect, 16);
@@ -32,6 +43,18 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Rect, 16);
  * @addtogroup Functions
  * @{
  */
+
+/**
+ * PP_MakeRectFromXYWH() creates a PP_Rect given x and y coordinates and width
+ * and height dimensions as int32_t values.
+ * @param[in] x An int32_t value representing a horizontal coordinate of a
+ * point, starting with 0 as the left-most coordinate.
+ * @param[in] y An int32_t value representing a vertical coordinate of a point,
+ * starting with 0 as the top-most coordinate.
+ * @param[in] w An int32_t value representing a width.
+ * @param[in] h An int32_t value representing a height.
+ * @return A PP_Rect structure.
+ */
 PP_INLINE struct PP_Rect PP_MakeRectFromXYWH(int32_t x, int32_t y,
                                              int32_t w, int32_t h) {
   struct PP_Rect ret;
diff --git a/ppapi/c/pp_size.h b/ppapi/c/pp_size.h
index e414376..be84040 100644
--- a/ppapi/c/pp_size.h
+++ b/ppapi/c/pp_size.h
@@ -7,7 +7,7 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the width and height of a 2 dimenstional rectangle.
  */
 
 #include "ppapi/c/pp_macros.h"
@@ -17,8 +17,14 @@
  * @addtogroup Structs
  * @{
  */
+
+/**
+ * The PP_Size struct contains the size of a 2D rectangle.
+ */
 struct PP_Size {
+  /** This value represents the width of the rectangle. */
   int32_t width;
+  /** This value represents the height of the rectangle. */
   int32_t height;
 };
 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Size, 8);
@@ -30,6 +36,13 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Size, 8);
  * @addtogroup Functions
  * @{
  */
+
+/**
+ * PP_MakeSize() creates a PP_Size given a width and height as int32_t values.
+ * @param[in] w An int32_t value representing a width.
+ * @param[in] h An int32_t value representing a height.
+ * @return A PP_Size structure.
+ */
 PP_INLINE struct PP_Size PP_MakeSize(int32_t w, int32_t h) {
   struct PP_Size ret;
   ret.width = w;
diff --git a/ppapi/c/pp_time.h b/ppapi/c/pp_time.h
index 6b84271..9e0fda0 100644
--- a/ppapi/c/pp_time.h
+++ b/ppapi/c/pp_time.h
@@ -7,7 +7,7 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines time and time ticks types.
  */
 
 #include "ppapi/c/pp_macros.h"
@@ -17,9 +17,9 @@
  * @{
  */
 /**
- * PP_Time represents the "wall clock time" according to the browser and is
- * defined as the number of seconds since the Epoch (00:00:00 UTC, January 1,
- * 1970).
+ * The PP_Time type represents the "wall clock time" according to the browser
+ * and is defined as the number of seconds since the Epoch (00:00:00 UTC,
+ * January 1, 1970).
  */
 typedef double PP_Time;
 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_Time, 8);
@@ -32,10 +32,11 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_Time, 8);
  * @{
  */
 /**
- * Represents time ticks which is measured in seconds and is used for indicating
- * the time that certain messages were received. In contrast to PP_Time, it
- * does not correspond to any actual wall clock time and will not change
- * discontinuously if the user changes their computer clock.
+ * A PP_TimeTicks value represents time ticks which are measured in seconds
+ * and are used for indicating the time that certain messages were received.
+ * In contrast to PP_Time, PP_TimeTicks does not correspond to any actual
+ * wall clock time and will not change discontinuously if the user changes
+ * their computer clock.
  *
  * The units are in seconds, but are not measured relative to any particular
  * epoch, so the most you can do is compare two values.