Added link to ppb.h to point to list of valid interface names. Wrote/rewrote docs in ppb_image_data.h

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

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

2 files changed, 77 insertions, 22 deletions

diff --git a/ppapi/c/ppb.h b/ppapi/c/ppb.h
index 8b06088..264c661 100644
--- a/ppapi/c/ppb.h
+++ b/ppapi/c/ppb.h
@@ -22,7 +22,10 @@
  * to request a pointer to a specific browser interface. Browser interface
  * names are ASCII strings and are generally defined in the header file for the
  * interface, such as PP_AUDIO_INTERFACE found in ppb.audio.h or
- * PPB_GRAPHICS_2D_INTERFACE in ppb_graphics_2d.h.
+ * PPB_GRAPHICS_2D_INTERFACE in ppb_graphics_2d.h. Click
+ * <a href="http://code.google.com/chrome/nativeclient/docs/reference/pepperc/
+ *globals_defs.html" title="macros">here</a> for a complete list of interface
+ * names.
  *
  * This value will be NULL if the interface is not supported on the browser.
  */
diff --git a/ppapi/c/ppb_image_data.h b/ppapi/c/ppb_image_data.h
index c9c6f99..bc014d4 100644
--- a/ppapi/c/ppb_image_data.h
+++ b/ppapi/c/ppb_image_data.h
@@ -15,7 +15,8 @@
 
 /**
  * @file
- * Defines the API ...
+ * This file defines the PPB_ImageData struct for determining how a browser
+ * handles image data.
  */
 
 /**
@@ -23,6 +24,10 @@
  * @{
  */
 
+/**
+ * PP_ImageDataFormat is an enumeration of the different types of
+ * image data formats.
+ */
 typedef enum {
   PP_IMAGEDATAFORMAT_BGRA_PREMUL,
   PP_IMAGEDATAFORMAT_RGBA_PREMUL
@@ -36,14 +41,24 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_ImageDataFormat, 4);
  * @addtogroup Structs
  * @{
  */
+
+/**
+ * The PP_ImageDataDesc structure represents a description of image data.
+ */
 struct PP_ImageDataDesc {
+
+  /**
+   * This value represents one of the image data types in the
+   * PP_ImageDataFormat enum.
+   */
   PP_ImageDataFormat format;
 
-  /** Size of the bitmap in pixels. */
+  /** This value represents the size of the bitmap in pixels. */
   struct PP_Size size;
 
-  /** The row width in bytes. This may be different than width * 4 since there
-   * may be padding at the end of the lines.
+  /**
+   * This value represents the row width in bytes. This may be different than
+   * width * 4 since there may be padding at the end of the lines.
    */
   int32_t stride;
 };
@@ -58,33 +73,51 @@ PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_ImageDataDesc, 16);
  * @addtogroup Interfaces
  * @{
  */
+
+/**
+ * The PPB_ImageData interface contains pointers to several functions for
+ * determining the browser's treatment of image data.
+ */
 struct PPB_ImageData {
   /**
-   * Returns the browser's preferred format for image data. This format will be
-   * the format is uses internally for painting. Other formats may require
-   * internal conversions to paint or may have additional restrictions depending
-   * on the function.
+   * GetNativeImageDataFormat is a pointer to a function that returns the
+   * browser's preferred format for image data. The browser uses this format
+   * internally for painting. Other formats may require internal conversions
+   * to paint or may have additional restrictions depending on the function.
+   *
+   * @return PP_ImageDataFormat containing the preferred format.
    */
   PP_ImageDataFormat (*GetNativeImageDataFormat)();
 
   /**
-   * Returns PP_TRUE if the given image data format is supported by the browser.
+   * IsImageDataFormatSupported is a pointer to a function that determines if
+   * the given image data format is supported by the browser.
+   *
+   * @param[in] format The image data format.
+   * @return PP_Bool with PP_TRUE if the given image data format is supported
+   * by the browser.
    */
   PP_Bool (*IsImageDataFormatSupported)(PP_ImageDataFormat format);
 
   /**
-   * Allocates an image data resource with the given format and size. The
-   * return value will have a nonzero ID on success, or zero on failure.
-   * Failure means the instance, image size, or format was invalid.
+   * Create is a pointer to a function that allocates an image data resource
+   * with the given format and size.
    *
+   * For security reasons, if uninitialized, the bitmap will not contain random
+   * memory, but may contain data from a previous image produced by the same
+   * plugin if the bitmap was cached and re-used.
+   *
+   * @param[in] instance A PP_Instance indentifying one instance of a module.
+   * @param[in] format The desired image data format.
+   * @param[in] size A pointer to a PP_Size containing the image size.
+   * @param[in] init_to_zero A PP_Bool to determine transparency at creation.
    * Set the init_to_zero flag if you want the bitmap initialized to
    * transparent during the creation process. If this flag is not set, the
    * current contents of the bitmap will be undefined, and the plugin should
    * be sure to set all the pixels.
    *
-   * For security reasons, if uninitialized, the bitmap will not contain random
-   * memory, but may contain data from a previous image produced by the same
-   * plugin if the bitmap was cached and re-used.
+   * @return A PP_Resource with a nonzero ID on succes or zero on failure.
+   * Failure means the instance, image size, or format was invalid.
    */
   PP_Resource (*Create)(PP_Instance instance,
                         PP_ImageDataFormat format,
@@ -92,25 +125,44 @@ struct PPB_ImageData {
                         PP_Bool init_to_zero);
 
   /**
-   * Returns PP_TRUE if the given resource is an image data. Returns PP_FALSE if
-   * the resource is invalid or some type other than an image data.
+   * IsImageData is a pointer to a function that determiens if a given resource
+   * is image data.
+   *
+   * @param[in] image_data A PP_Resource corresponding to image data.
+   * @return A PP_Bool with PP_TRUE if the given resrouce is an image data
+   * or PP_FALSE if the resource is invalid or some type other than image data.
    */
   PP_Bool (*IsImageData)(PP_Resource image_data);
 
   /**
-   * Computes the description of the image data. Returns PP_TRUE on success,
-   * PP_FALSE if the resource is not an image data. On PP_FALSE, the |desc|
+   * Describe is a pointer to a function that computes the description of the
+   * image data.
+   *
+   * @param[in] image_data A PP_Resource corresponding to image data.
+   * @param[in/out] desc A pointer to a PP_ImageDataDesc containing the
+   * description.
+   * @return A PP_Bool with PP_TRUE on success or PP_FALSE
+   * if the resource is not an image data. On PP_FALSE, the |desc|
    * structure will be filled with 0.
    */
   PP_Bool (*Describe)(PP_Resource image_data,
                       struct PP_ImageDataDesc* desc);
 
   /**
-   * Maps this bitmap into the plugin address space and returns a pointer to the
-   * beginning of the data.
+   * Map is a pointer to a function that maps an image data into the plugin
+   * address space.
+   *
+   * @param[in] image_data A PP_Resource corresponding to image data.
+   * @return A pointer to the beginning of the data.
    */
   void* (*Map)(PP_Resource image_data);
 
+  /**
+   * Unmap is a pointer to a function that unmaps an image data from the plugin
+   * address space.
+   *
+   * @param[in] image_data A PP_Resource corresponding to image data.
+   */
   void (*Unmap)(PP_Resource image_data);
 };
 /**