Misc. changes. Mostly formatting.

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

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

13 files changed, 481 insertions, 374 deletions

diff --git a/ppapi/c/ppb.h b/ppapi/c/ppb.h
index efb19af..52a35f0 100644
--- a/ppapi/c/ppb.h
+++ b/ppapi/c/ppb.h
@@ -7,7 +7,8 @@
 
 /**
  * @file
- * This file defines a function pointer type for the PPB_GetInterface function.
+ * This file defines a function pointer type for the
+ * <code>PPB_GetInterface</code> function.
  */
 
 /**
@@ -16,15 +17,18 @@
  */
 
 /**
- * This function pointer type defines the signature for the PPB_GetInterface
- * function. A generic PPB_GetInterface pointer is passed to
- * PPP_InitializedModule when your module is loaded. You can use this pointer
- * 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. Click
+ * This function pointer type defines the signature for the
+ * <code>PPB_GetInterface</code> function. A generic
+ * <code>PPB_GetInterface</code> pointer is passed to
+ * <code>PPP_InitializedModule</code> when your module is loaded. You can use
+ * this pointer 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 <code>PPB_AUDIO_INTERFACE</code> found in
+ * <code>ppb.audio.h</code> or
+ * <code>PPB_GRAPHICS_2D_INTERFACE</code> in <code>ppb_graphics_2d.h</code>.
+ * Click
  * <a href="/chrome/nativeclient/docs/reference/pepperc/
- *globals_defs.html" title="macros">here</a> for a complete list of interface
+ * 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_audio.h b/ppapi/c/ppb_audio.h
index 6fb2978..39d02b5 100644
--- a/ppapi/c/ppb_audio.h
+++ b/ppapi/c/ppb_audio.h
@@ -89,6 +89,7 @@ struct PPB_Audio {
   * @param[in] audio_callback A PPB_Audio_Callback callback function that the
   * browser calls when it needs more samples to play.
   * @param[in] user_data A pointer to user data used in the callback function.
+  *
   * @return A PP_Resource containing the audio resource if successful or
   * 0 if the configuration cannot be honored or the callback is null.
   */
@@ -99,6 +100,7 @@ struct PPB_Audio {
    * resource is an audio resource.
    *
    * @param[in] resource A PP_Resource containing a resource.
+   *
    * @return A PP_BOOL containing containing PP_TRUE if the given resource is
    * an Audio resource, otherwise PP_FALSE.
    */
@@ -109,6 +111,7 @@ struct PPB_Audio {
    * resource for the given audio resource.
    *
    * @param[in] config A PP_Resource containing the audio resource.
+   *
    * @return A PP_Resource containing the audio config resource if successful.
    */
   PP_Resource (*GetCurrentConfig)(PP_Resource audio);
@@ -118,6 +121,7 @@ struct PPB_Audio {
    * the audio resource and begins periodically calling the callback.
    *
    * @param[in] config A PP_Resource containing the audio resource.
+   *
    * @return A PP_BOOL containing PP_TRUE if successful, otherwise PP_FALSE.
    * Also returns PP_TRUE (and be a no-op) if called while playback is already
    * in progress.
@@ -129,6 +133,7 @@ struct PPB_Audio {
    * the audio resource.
    *
    * @param[in] config A PP_Resource containing the audio resource.
+   *
    * @return A PP_BOOL containing PP_TRUE if successful, otherwise PP_FALSE.
    * Also returns PP_TRUE (and is a no-op) if called while playback is already
    * stopped. If a callback is in progress, StopPlayback will block until the
diff --git a/ppapi/c/ppb_audio_config.h b/ppapi/c/ppb_audio_config.h
index 5ae4afe..033ac3c 100644
--- a/ppapi/c/ppb_audio_config.h
+++ b/ppapi/c/ppb_audio_config.h
@@ -106,6 +106,7 @@ struct PPB_AudioConfig {
    * <code>PP_AUDIOSAMPLERATE_48000</code>.
    * @param[in] sample_frame_count A <code>uint32_t</code> frame count returned
    * from the <code>RecommendSampleFrameCount</code> function.
+   *
    * @return A <code>PP_Resource</code> containing the
    * <code>PPB_Audio_Config</code> if successful or a null resource if the
    * sample frame count or bit rate are not supported.
@@ -133,6 +134,7 @@ struct PPB_AudioConfig {
    * <code>PP_AUDIOSAMPLERATE_48000.</code>
    * @param[in] requested_sample_frame_count A <code>uint_32t</code> requested
    * frame count.
+   *
    * @return A <code>uint32_t</code> containing the recommended sample frame
    * count if successful.
    */
@@ -145,6 +147,7 @@ struct PPB_AudioConfig {
    *
    * @param[in] resource A <code>PP_Resource</code> containing the audio config
    * resource.
+   *
    * @return A <code>PP_BOOL</code> containing <code>PP_TRUE</code> if the given
    * resource is an <code>AudioConfig</code> resource, otherwise
    * <code>PP_FALSE</code>.
@@ -157,6 +160,7 @@ struct PPB_AudioConfig {
    *
    * @param[in] config A <code>PP_Resource</code> containing the
    * <code>PPB_Audio_Config</code>.
+   *
    * @return A <code>PP_AudioSampleRate</code> containing sample rate or
    * <code>PP_AUDIOSAMPLERATE_NONE</code> if the resource is invalid.
    */
@@ -168,6 +172,7 @@ struct PPB_AudioConfig {
    *
    * @param[in] config A <code>PP_Resource</code> containing the audio config
    * resource.
+   *
    * @return A <code>uint32_t</code> containing sample frame count or
    * 0 if the resource is invalid. See <code>RecommendSampleFrameCount</code>
    * for more on sample frame counts.
diff --git a/ppapi/c/ppb_core.h b/ppapi/c/ppb_core.h
index 968dfcd..e409d48 100644
--- a/ppapi/c/ppb_core.h
+++ b/ppapi/c/ppb_core.h
@@ -18,9 +18,9 @@ struct PP_CompletionCallback;
 
 /**
  * @file
- * This file defines the PPB_Core interface defined by the browser and
- * and containing pointers to functions related to memory management,
- * time, and threads.
+ * This file defines the <code>PPB_Core</code> interface defined by the browser
+ * and containing pointers to functions related to memory management, time, and
+ * threads.
  */
 
 /**
@@ -29,65 +29,63 @@ struct PP_CompletionCallback;
  */
 
 /**
- * The PPB_Core interface contains pointers to functions related to memory
- * management, time, and threads on the browser.
+ * The <code>PPB_Core</code> interface contains pointers to functions related
+ * to memory management, time, and threads on the browser.
  *
  */
 struct PPB_Core {
   /**
-   * 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.
+   * AddRefResource() adds a reference to a resource.
+   *
+   * @param[in] config A <code>PP_Resource</code> containing the resource.
    */
   void (*AddRefResource)(PP_Resource resource);
 
   /**
-   * ReleaseResource is a pointer to a function that removes a reference
-   * from a resource.
+   * ReleaseResource() removes a reference from a resource.
    *
-   * @param[in] config A PP_Resource containing the resource.
+   * @param[in] config A <code>PP_Resource</code> containing the resource.
    */
-/*Same as ReleaseVar for Resources. */
   void (*ReleaseResource)(PP_Resource resource);
 
   /**
-   * MemAlloc is a pointer to a function that allocate memory.
+   * MemAlloc() allocates memory.
    *
    * @param[in] num_bytes A number of bytes to allocate.
-   * @return A pointer to the memory if successful, NULL If the
+   *
+   * @return A pointer to the memory if successful, <code>NULL</code> If the
    * allocation fails.
    */
   void* (*MemAlloc)(uint32_t num_bytes);
 
   /**
-   * MemFree is a pointer to a function that deallocates memory.
+   * <code>MemFree()</code> deallocates memory.
    *
    * @param[in] ptr A pointer to the memory to deallocate. It is safe to
-   * pass NULL to this function.
+   * pass <code>NULL</code> to this function.
    */
   void (*MemFree)(void* ptr);
 
   /**
-   * GetTime is a pointer to a function that returns the "wall clock
-   * time" according to the browser.
-   *
-   * @return A PP_Time containing the "wall clock time" according to the
+   * GetTime() returns the "wall clock time" according to the
    * browser.
+   *
+   * @return A <code>PP_Time</code> containing the "wall clock time" according
+   * to the browser.
    */
   PP_Time (*GetTime)();
 
   /**
-   * 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.
+   * GetTimeTicks() returns the "tick time" according to the browser.
+   * This clock is used by the browser when passing some event times to the
+   * module (e.g. using the <code>PP_InputEvent::time_stamp_seconds</code>
+   * 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.
    *
-   * @return A PP_TimeTicks containing the "tick time" according to the
-   * browser.
+   * @return A <code>PP_TimeTicks</code> containing the "tick time" according
+   * to the browser.
    */
 
 // TODO(brettw) http://code.google.com/p/chromium/issues/detail?id=57448
@@ -96,40 +94,41 @@ struct PPB_Core {
   PP_TimeTicks (*GetTimeTicks)();
 
   /**
-   * 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.
+   * CallOnMainThread() 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 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.
+   * The <code>result</code> parameter will just be passed as the second
+   * argument to the callback. Many applications won't need this, but it allows
+   * a module to emulate calls of some callbacks which do use this value.
    *
-   * NOTE: CallOnMainThread, even when used from the main thread with a delay
-   * of 0 milliseconds, will never directly invoke the callback.  Even in this
-   * case, the callback will be scheduled asynchronously.
+   * <strong>Note:</strong> CallOnMainThread, even when used from the main
+   * thread with a delay of 0 milliseconds, will never directly invoke the
+   * callback.  Even in this case, the callback will be scheduled
+   * asynchronously.
    *
-   * NOTE: If the browser is shutting down or if the plugin has no instances,
-   * then the callback function may not be called.
+   * <strong>Note:</strong> If the browser is shutting down or if the module
+   * 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] callback A <code>PP_CompletionCallback</code> 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.
+   * <code>PP_CompletionCallback</code>.
    */
   void (*CallOnMainThread)(int32_t delay_in_milliseconds,
                            struct PP_CompletionCallback callback,
                            int32_t result);
 
   /**
-   * IsMainThread is a pointer to a function that returns true if the
-   * current thread is the main pepper thread.
+   * IsMainThread() 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.
    *
-   * @return A PP_BOOL containing PP_TRUE if the current thread is the main
-   * pepper thread, otherwise PP_FALSE.
+   * @return A <code>PP_Bool</code> containing <code>PP_TRUE</code> if the
+   * current thread is the main pepper thread, otherwise <code>PP_FALSE</code>.
    */
   PP_Bool (*IsMainThread)();
 };
diff --git a/ppapi/c/ppb_graphics_2d.h b/ppapi/c/ppb_graphics_2d.h
index d32ef5d..1fc33da 100644
--- a/ppapi/c/ppb_graphics_2d.h
+++ b/ppapi/c/ppb_graphics_2d.h
@@ -21,78 +21,110 @@ struct PP_Size;
 
 /**
  * @file
- * Defines the PPB_Graphics2D struct.
+ * Defines the <code>PPB_Graphics2D</code> struct representing a 2D graphics
+ * context within the browser.
  *
  * @addtogroup Interfaces
  * @{
  */
 
-/** {PENDING: describe PPB_Graphics2D. */
+/**
+ * <code>PPB_Graphics2D</code> defines the interface for a 2D graphics context.
+ */
 struct PPB_Graphics2D {
   /**
-   * The returned graphics context will not be bound to the plugin instance on
-   * creation (call BindGraphics on the plugin instance to do that).
+   * Create() creates a 2D graphics context. The returned graphics context will
+   * not be bound to the module instance on creation (call BindGraphics() on
+   * the module instance to bind the returned graphics context to the module
+   * instance).
    *
-   * Set the is_always_opaque flag if you know that you will be painting only
-   * opaque data to this context. This will disable blending when compositing
-   * the plugin with the web page, which will give slightly higher performance.
+   * @param[in] instance The module instance.
+   * @param[in] size The size of the graphic context.
+   * @param[in] is_always_opaque Set the <code>is_always_opaque</code> flag to
+   * <code>PP_TRUE</code> if you know that you will be painting only opaque
+   * data to this context. This option will disable blending when compositing
+   * the module with the web page, which might give higher performance on some
+   * computers.
    *
-   * If you set is_always_opaque, your alpha channel should always be set to
-   * 0xFF or there may be painting artifacts. Being opaque will allow the
-   * browser to do a memcpy rather than a blend to paint the plugin, and this
-   * means your alpha values will get set on the page backing store. If these
-   * values are incorrect, it could mess up future blending.
+   * If you set <code>is_always_opaque</code>, your alpha channel should always
+   * be set to 0xFF or there may be painting artifacts. The alpha values
+   * overwrite the destination alpha values without blending when
+   * <code>is_always_opaque</code> is true.
    *
-   * If you aren't sure, it is always correct to specify that it it not opaque.
+   * @return A <code>PP_Resource</code> containing the 2D graphics context if
+   * successful or 0 if unsuccessful.
    */
   PP_Resource (*Create)(PP_Instance instance,
                         const struct PP_Size* size,
                         PP_Bool is_always_opaque);
 
   /**
-   * Returns PP_TRUE if the given resource is a valid Graphics2D, PP_FALSE if it
-   * is an invalid resource or is a resource of another type.
+   * IsGraphics2D() determines if the given resource is a valid
+   * <code>Graphics2D</code>.
+   *
+   * @param[in] resource A <code>Graphics2D</code> context resource.
+   *
+   * @return PP_TRUE if the given resource is a valid <code>Graphics2D</code>,
+   * <code>PP_FALSE</code> if it is an invalid resource or is a resource of
+   * another type.
    */
   PP_Bool (*IsGraphics2D)(PP_Resource resource);
 
   /**
-   * Retrieves the configuration for the given graphics context, filling the
-   * given values (which must not be NULL). On success, returns PP_TRUE. If the
-   * resource is invalid, the output parameters will be set to 0 and it will
-   * return PP_FALSE.
+   * Describe() retrieves the configuration for the given graphics context,
+   * filling the given values (which must not be <code>NULL</code>).
+   *
+   * @param[in] resource The 2D Graphics resource.
+   * @param[in,out] size The size of the 2D graphics context in the browser.
+   * @param[in,out] is_always_opaque Identifies whether only opaque data
+   * will be painted.
+   *
+   * @return Returns <code>PP_TRUE</code> on succes or <code>PP_FALSE</code> if
+   * the resource is invalid. The output parameters will be set to 0 on a
+   * <code>PP_FALSE</code>.
    */
   PP_Bool (*Describe)(PP_Resource graphics_2d,
                       struct PP_Size* size,
                       PP_Bool* is_always_opqaue);
 
   /**
-   * Enqueues a paint of the given image into the context. THIS HAS NO EFFECT
-   * UNTIL YOU CALL Flush(). As a result, what counts is the contents of the
-   * bitmap when you call Flush, not when you call this function.
+   * PaintImageData() enqueues a paint of the given image into the context.
+   * This function has no effect until you call Flush() As a result, what
+   * counts is the contents of the bitmap when you call Flush(), not when
+   * you call this function.
    *
-   * The given image will be placed at |top_left| from the top left of the
-   * context's internal backing store. Then the src_rect will be copied into the
-   * backing store. This parameter may not be NULL. This means that the
-   * rectangle being painted will be at src_rect offset by top_left.
+   * The provided image will be placed at <code>top_left</code> from the top
+   *  left of the context's internal backing store. Then the pixels contained
+   * in <code>src_rect</code> will be copied into the backing store. This
+   * means that the rectangle being painted will be at <code>src_rect</code>
+   * offset by <code>top_left</code>.
    *
-   * The src_rect is specified in the coordinate system of the image being
-   * painted, not the context. For the common case of copying the entire image,
-   * you may specify a NULL |src_rect| pointer. If you are frequently updating
-   * the entire image, consider using ReplaceContents which will give slightly
-   * higher performance.
+   * The <code>src_rect</code> is specified in the coordinate system of the
+   * image being painted, not the context. For the common case of copying the
+   * entire image, you may specify an empty <code>src_rect</code>.
    *
    * The painted area of the source bitmap must fall entirely within the
    * context. Attempting to paint outside of the context will result in an
    * error. However, the source bitmap may fall outside the context, as long
-   * as the src_rect subset of it falls entirely within the context.
-   *
-   * There are two modes most plugins may use for painting. The first is
-   * that you will generate a new ImageData (possibly representing a subset of
-   * your plugin) and then paint it. In this case, you'll set the location of
-   * your painting to top_left and set src_rect to NULL. The second is that
-   * you're generating small invalid regions out of a larger bitmap
-   * representing your entire plugin. In this case, you would set the location
-   * of your image to (0,0) and then set src_rect to the pixels you changed.
+   * as the <code>src_rect</code> subset of it falls entirely within the
+   * context.
+   *
+   * There are two methods most modules will use for painting. The first
+   * method is to generate a new <code>ImageData</code> and then paint it. In
+   * this case, you'll set the location of your painting to
+   * <code>top_left</code> and set <code>src_rect</code> to <code>NULL</code>.
+   * The second is that you're generating small invalid regions out of a larger
+   * bitmap representing your entire instance. In this case, you would set the
+   * location of your image to (0,0) and then set <code>src_rect</code> to the
+   * pixels you changed.
+   *
+   * @param[in] resource The 2D Graphics resource.
+   * @param[in] image The <code>ImageData</code> to be painted.
+   * @param[in] top_left A <code>Point</code> representing the
+   * <code>top_left</code> location where the <code>ImageData</code> will be
+   * painted.
+   * @param[in] src_rect The rectangular area where the <code>ImageData</code>
+   * will be painted.
    */
   void (*PaintImageData)(PP_Resource graphics_2d,
                          PP_Resource image_data,
@@ -100,39 +132,45 @@ struct PPB_Graphics2D {
                          const struct PP_Rect* src_rect);
 
   /**
-   * Enqueues a scroll of the context's backing store. THIS HAS NO EFFECT UNTIL
-   * YOU CALL Flush(). The data within the given clip rect (you may specify
-   * NULL to scroll the entire region) will be shifted by (dx, dy) pixels.
+   * Scroll() enqueues a scroll of the context's backing store. This
+   * function has no effect until you call Flush(). The data within the
+   * provided clipping rectangle will be shifted by (dx, dy) pixels.
    *
-   * This will result in some exposed region which will have undefined
-   * contents. The plugin should call PaintImageData on these exposed regions
+   * This function will result in some exposed region which will have undefined
+   * contents. The module should call PaintImageData() on these exposed regions
    * to give the correct contents.
    *
-   * The scroll can be larger than the area of the clip rect, which means the
-   * current image will be scrolled out of the rect. This is not an error but
-   * will be a no-op.
+   * The scroll can be larger than the area of the clipping rectangle, which
+   * means the current image will be scrolled out of the rectangle. This
+   * scenario is not an error but will result in a no-op.
+   *
+   * @param[in] graphics_2d The 2D Graphics resource.
+   * @param[in] clip The clipping rectangle.
+   * @param[in] amount The amount the area in the clipping rectangle will
+   * shifted.
    */
   void (*Scroll)(PP_Resource graphics_2d,
                  const struct PP_Rect* clip_rect,
                  const struct PP_Point* amount);
 
   /**
-   * This function provides a slightly more efficient way to paint the entire
-   * plugin's image. Normally, calling PaintImageData requires that the browser
-   * copy the pixels out of the image and into the graphics context's backing
-   * store. This function replaces the graphics context's backing store with the
-   * given image, avoiding the copy.
+   * ReplaceContents() provides a slightly more efficient way to paint the
+   * entire module's image. Normally, calling PaintImageData() requires that
+   * the browser copy the pixels out of the image and into the graphics
+   * context's backing store. This function replaces the graphics context's
+   * backing store with the given image, avoiding the copy.
    *
    * The new image must be the exact same size as this graphics context. If the
    * new image uses a different image format than the browser's native bitmap
-   * format (use PPB_ImageData.GetNativeImageDataFormat to retrieve this), then
-   * a conversion will be done inside the browser which may slow the performance
-   * a little bit.
+   * format (use <code>PPB_ImageData.GetNativeImageDataFormat()</code> to
+   * retrieve the format), then a conversion will be done inside the browser
+   * which may slow the performance a little bit.
    *
-   * THE NEW IMAGE WILL NOT BE PAINTED UNTIL YOU CALL FLUSH.
+   * <strong>Note:</strong> The new image will not be painted until you call
+   * Flush().
    *
    * After this call, you should take care to release your references to the
-   * image. If you paint to the image after ReplaceContents, there is the
+   * image. If you paint to the image after ReplaceContents(), there is the
    * possibility of significant painting artifacts because the page might use
    * partially-rendered data when copying out of the backing store.
    *
@@ -143,85 +181,82 @@ struct PPB_Graphics2D {
    * the sizes match). In the optimal case, this means no bitmaps are allocated
    * during the animation, and the backing store and "front buffer" (which the
    * plugin is painting into) are just being swapped back and forth.
+   *
+   * @param[in] graphics_2d The 2D Graphics resource.
+   * @param[in] image The <code>ImageData</code> to be painted.
    */
   void (*ReplaceContents)(PP_Resource graphics_2d, PP_Resource image_data);
 
   /**
-   * Flushes any enqueued paint, scroll, and replace commands for the backing
-   * store. This actually executes the updates, and causes a repaint of the
-   * webpage, assuming this graphics context is bound to a plugin instance. This
-   * can run in two modes:
-   *
-   * - In synchronous mode, you specify NULL for the callback and the callback
-   *   data. This function will block the calling thread until the image has
-   *   been painted to the screen. It is not legal to block the main thread of
-   *   the plugin, you can use synchronous mode only from background threads.
-   *
-   * - In asynchronous mode, you specify a callback function and the argument
-   *   for that callback function. The callback function will be executed on
-   *   the calling thread when the image has been painted to the screen. While
-   *   you are waiting for a Flush callback, additional calls to Flush will
-   *   fail.
+   * Flush() flushes any enqueued paint, scroll, and replace commands to the
+   * backing store. This function actually executes the updates, and causes a
+   * repaint of the webpage, assuming this graphics context is bound to a module
+   * instance.
+   *
+   * Flush() runs in asynchronous mode. Specify a callback function and the
+   * argument for that callback function. The callback function will be
+   * executed on the calling thread when the image has been painted to the
+   * screen. While you are waiting for a flush callback, additional calls to
+   * Flush() will fail.
    *
    * Because the callback is executed (or thread unblocked) only when the
-   * plugin's current state is actually on the screen, this function provides a
-   * way to rate limit animations. By waiting until the image is on the screen
-   * before painting the next frame, you can ensure you're not generating
-   * updates faster than the screen can be updated.
-   *
-   * <dl>
-   * <dt>Unbound contexts</dt>
-   * <dd>
-   *   If the context is not bound to a plugin instance, you will
-   *   still get a callback. It will execute after the Flush function returns
-   *   to avoid reentrancy. Of course, it will not wait until anything is
-   *   painted to the screen because there will be nothing on the screen. The
-   *   timing of this callback is not guaranteed and may be deprioritized by
-   *   the browser because it is not affecting the user experience.
-   * </dd>
-   *
-   * <dt>Off-screen instances</dt>
-   * <dd>
-   *   If the context is bound to an instance that is
-   *   currently not visible (for example, scrolled out of view) it will behave
-   *   like the "unbound context" case.
-   * </dd>
-   *
-   * <dt>Detaching a context</dt>
-   * <dd>
-   *   If you detach a context from a plugin instance, any
-   *   pending flush callbacks will be converted into the "unbound context"
-   *   case.
-   * </dd>
-   *
-   * <dt>Released contexts</dt>
-   * <dd>
-   *   A callback may or may not still get called even if you have released all
-   *   of your references to the context. This can occur if there are internal
-   *   references to the context that means it has not been internally
-   *   destroyed (for example, if it is still bound to an instance) or due to
-   *   other implementation details. As a result, you should be careful to
-   *   check that flush callbacks are for the context you expect and that
-   *   you're capable of handling callbacks for context that you may have
-   *   released your reference to.
-   * </dd>
-   *
-   * <dt>Shutdown</dt>
-   * <dd>
-   *   If a plugin instance is removed when a Flush is pending, the
-   *   callback will not be executed.
-   * </dd>
-   * </dl>
-   *
-   * Returns PP_OK on success, PP_Error_BadResource if the graphics context is
-   * invalid, PP_Error_BadArgument if the callback is null and Flush is being
-   * called from the main thread of the plugin, or PP_Error_InProgress if a
-   * Flush is already pending that has not issued its callback yet.  In the
-   * failure case, nothing will be updated and no callback will be scheduled.
+   * instance's image is actually on the screen, this function provides
+   * a way to rate limit animations. By waiting until the image is on the
+   * screen before painting the next frame, you can ensure you're not
+   * flushing 2D graphics faster than the screen can be updated.
+   *
+   * <strong>Unbound contexts</strong>
+   * If the context is not bound to a module instance, you will
+   * still get a callback. The callback will execute after Flush() returns
+   * to avoid reentrancy. The callback will not wait until anything is
+   * painted to the screen because there will be nothing on the screen. The
+   * timing of this callback is not guaranteed and may be deprioritized by
+   * the browser because it is not affecting the user experience.
+   *
+   * <strong>Off-screen instances</strong>
+   * If the context is bound to an instance that is currently not visible (for
+   * example, scrolled out of view) it will behave like the "unbound context"
+   * case.
+   *
+   * <strong>Detaching a context</strong>
+   * If you detach a context from a module instance, any pending flush
+   * callbacks will be converted into the "unbound context" case.
+   *
+   * <strong>Released contexts</strong>
+   * A callback may or may not get called even if you have released all
+   * of your references to the context. This scenario can occur if there are
+   * internal references to the context suggesting it has not been internally
+   * destroyed (for example, if it is still bound to an instance) or due to
+   * other implementation details. As a result, you should be careful to
+   * check that flush callbacks are for the context you expect and that
+   * you're capable of handling callbacks for unreferenced contexts.
+   *
+   * <strong>Shutdown</strong>
+   * If a module instance is removed when a flush is pending, the
+   * callback will not be executed.
+   *
+   * @param[in] graphics_2d The 2D Graphics resource.
+   * @param[in] callback A <code>CompletionCallback</code> to be called when
+   * the image has been painted on the screen.
+   *
+   * @return Returns <code>PP_OK</code> on success or
+   * <code>PP_Error_BadResource</code> if the graphics context is invalid,
+   * <code>PP_Error_BadArgument</code> if the callback is null and flush is
+   * being called from the main thread of the module, or
+   * <code>PP_Error_InProgress</code> if a flush is already pending that has
+   * not issued its callback yet.  In the failure case, nothing will be updated
+   * and no callback will be scheduled.
    */
-  /* TODO(darin): We should ensure that the completion callback always runs, so
+
+  /*
+   * TODO(darin): We should ensure that the completion callback always runs, so
    * that it is easier for consumers to manage memory referenced by a callback.
    */
+
+  /*
+   * TODO(): Add back in the synchronous mode description once we have support
+   * for it.
+   */
   int32_t (*Flush)(PP_Resource graphics_2d,
                    struct PP_CompletionCallback callback);
 
diff --git a/ppapi/c/ppb_image_data.h b/ppapi/c/ppb_image_data.h
index 41456095..d7c8c82 100644
--- a/ppapi/c/ppb_image_data.h
+++ b/ppapi/c/ppb_image_data.h
@@ -53,8 +53,8 @@
  * </code>
  * <code>uint8_t image_data_alpha_premul = (uint8_t)(alpha * 255.0f);</code>
  *
- * Note: The resulting pre-multiplied red, green and blue components should not
- * be greater than the alpha value.
+ * <strong>Note:</strong> The resulting pre-multiplied red, green and blue
+ * components should not be greater than the alpha value.
  */
 typedef enum {
   PP_IMAGEDATAFORMAT_BGRA_PREMUL,
@@ -124,6 +124,7 @@ struct PPB_ImageData {
    * supported by the browser.
    *
    * @param[in] format The image data format.
+   *
    * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
    * image data format is supported by the browser.
    */
@@ -161,6 +162,7 @@ struct PPB_ImageData {
    *
    * @param[in] image_data A <code>PP_Resource</code> corresponding to image
    * data.
+   *
    * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
    * resrouce is an image data or <code>PP_FALSE</code> if the resource is
    * invalid or some type other than image data.
@@ -175,6 +177,7 @@ struct PPB_ImageData {
    * data.
    * @param[in,out] desc A pointer to a <code>PP_ImageDataDesc</code>
    * containing the description.
+   *
    * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> on success or
    * <code>PP_FALSE</code> if the resource is not an image data. On
    * <code>PP_FALSE</code>, the <code>desc</code> structure will be filled
@@ -188,6 +191,7 @@ struct PPB_ImageData {
    *
    * @param[in] image_data A <code>PP_Resource</code> corresponding to image
    * data.
+   *
    * @return A pointer to the beginning of the data.
    */
   void* (*Map)(PP_Resource image_data);
diff --git a/ppapi/c/ppb_messaging.h b/ppapi/c/ppb_messaging.h
index 951d5d4..5312323 100644
--- a/ppapi/c/ppb_messaging.h
+++ b/ppapi/c/ppb_messaging.h
@@ -13,41 +13,42 @@
 
 /**
  * @file
- * This file defines the PPB_Messaging interface implemented by the browser
- * related to sending messages to DOM elements associated with a specific
- * module instance.
+ * This file defines the <code>PPB_Messaging</code> interface implemented
+ * by the browser for sending messages to DOM elements associated with a
+ * specific module instance.
  *
  * @addtogroup Interfaces
  * @{
  */
 
 /**
- * The PPB_Messaging interface contains a pointer to a function related to
- * sending messages to JavaScript message event listeners on the DOM element
- * associated with a specific module instance.
+ * The <code>PPB_Messaging</code> interface is implemented by the browser
+ * and is related to sending messages to JavaScript message event listeners on
+ * the DOM element associated with specific module instance.
  */
 struct PPB_Messaging {
   /**
-   * PostMessage is a pointer to a function that asynchronously invokes any
-   * listeners for message events on the DOM element for the given module
-   * instance. A call to PostMessage() will not block while the message is
-   * processed.
+   * PostMessage() asynchronously invokes any listeners for message events on
+   * the DOM element for the given module instance. A call to PostMessage()
+   * will not block while the message is processed.
    *
-   * @param[in] instance A PP_Instance indentifying one instance of a module.
-   * @param[in] message A PP_Var containing the data to be sent to JavaScript.
+   * @param[in] instance A <code>PP_Instance</code> indentifying one instance
+   * of a module.
+   * @param[in] message A <code>PP_Var</code> containing the data to be sent to
+   * JavaScript.
    * Message can have a numeric, boolean, or string value; arrays and
    * dictionaries are not yet supported. Ref-counted var types are copied, and
    * are therefore not shared between the module instance and the browser.
    *
    * Listeners for message events in JavaScript code will receive an object
-   * conforming to the HTML 5 MessageEvent interface. Specifically, the value of
-   * message will be contained as a property called data in the received
-   * MessageEvent.
+   * conforming to the HTML 5 <code>MessageEvent</code> interface.
+   * Specifically, the value of message will be contained as a property called
+   *  data in the received <code>MessageEvent</code>.
    *
    * This messaging system is similar to the system used for listening for
    * messages from Web Workers. Refer to
-   * http://www.whatwg.org/specs/web-workers/current-work/ for further
-   * information.
+   * <code>http://www.whatwg.org/specs/web-workers/current-work/</code> for
+   * further information.
    *
    * <strong>Example:</strong>
    *
diff --git a/ppapi/c/ppb_url_loader.h b/ppapi/c/ppb_url_loader.h
index afbee22..8c5d7dd 100644
--- a/ppapi/c/ppb_url_loader.h
+++ b/ppapi/c/ppb_url_loader.h
@@ -54,6 +54,7 @@ struct PPB_URLLoader {
    *
    * @param[in] instance A <code>PP_Instance</code> indentifying one instance
    * of a module.
+   *
    * @return A <code>PP_Resource</code> corresponding to a URLLoader if
    * successful, 0 if the instance is invalid.
    */
@@ -64,6 +65,7 @@ struct PPB_URLLoader {
    *
    * @param[in] resource A <code>PP_Resource</code> corresponding to a
    * <code>URLLoader</code>.
+   *
    * @return <code>PP_TRUE</code> if the resource is a <code>URLLoader</code>, 
    * <code>PP_FALSE</code> if the resource is invalid or some type other
    * than <code>URLLoader</code>.
@@ -83,6 +85,8 @@ struct PPB_URLLoader {
    * asynchronous completion of Open(). This callback will run when response
    * headers for the url are received or error occured. This callback
    * will only run if Open() returns <code>PP_OK_COMPLETIONPENDING</code>.
+   *
+   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
    */
   int32_t (*Open)(PP_Resource loader,
                   PP_Resource request_info,
@@ -99,6 +103,7 @@ struct PPB_URLLoader {
    * response headers for the redirect url are received or error occured. This
    * callback will only run if FollowRedirect() returns
    * <code>PP_OK_COMPLETIONPENDING</code>.
+   *
    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
    */
   int32_t (*FollowRedirect)(PP_Resource loader,
@@ -117,6 +122,7 @@ struct PPB_URLLoader {
    * <code>URLLoader</code>.
    * @param[in] bytes_sent The number of bytes sent thus far.
    * @param[in] total_bytes_to_be_sent The total number of bytes to be sent.
+   *
    * @return <code>PP_TRUE</code> if the upload progress is available, 
    * <code>PP_FALSE</code> if it is not available.
    */
@@ -139,6 +145,7 @@ struct PPB_URLLoader {
    * @param[in] total_bytes_to_be_received The total number of bytes to be
    * received. The total bytes to be received may be unknown, in which case
    * <code>total_bytes_to_be_received</code> will be set to -1.
+   *
    * @return <code>PP_TRUE</code> if the download progress is available,
    * <code>PP_FALSE</code> if it is not available.
    */
@@ -151,6 +158,7 @@ struct PPB_URLLoader {
    *
    * @param[in] instance A <code>PP_Resource</code> corresponding to a
    * <code>URLLoader</code>.
+   *
    * @return A <code>PP_Resource</code> corresponding to the
    * <code>URLResponseInfo</code> if successful, 0 if the loader is not a valid
    * resource or if Open() has not been called.
@@ -170,6 +178,7 @@ struct PPB_URLLoader {
    * asynchronous completion. The callback will run if the bytes (full or
    * partial) are read or an error occurs asynchronously. This callback will
    * run only if this function returns <code>PP_OK_COMPLETIONPENDING</code>.
+   *
    * @return An int32_t containing the number of bytes read or an error code
    * from <code>pp_errors.h</code>.
    */
@@ -190,6 +199,7 @@ struct PPB_URLLoader {
    * asynchronous completion. This callback will run when body is downloaded
    * or an error occurs after FinishStreamingToFile() returns
    * <code>PP_OK_COMPLETIONPENDING</code>.
+   *
    * @return An int32_t containing the number of bytes read or an error code
    * from <code>pp_errors.h</code>.
    */
@@ -202,9 +212,9 @@ struct PPB_URLLoader {
    * reporting <code>PP_ERROR_ABORTED</code> if pending IO was interrupted.
    * It is NOT valid to call Open() again after a call to this function.
    *
-   * Note: If the <code>URLLoader</code> object is destroyed while it is still
-   * open, then it will be implicitly closed so you are not required to call
-   * Close().
+   * <strong>Note:</strong> If the <code>URLLoader</code> object is destroyed
+   * while it is still open, then it will be implicitly closed so you are not
+   * required to call Close().
    *
    * @param[in] loader A <code>PP_Resource</code> corresponding to a
    * <code>URLLoader</code>.
diff --git a/ppapi/c/ppb_url_request_info.h b/ppapi/c/ppb_url_request_info.h
index dea3ee7..3bded07 100644
--- a/ppapi/c/ppb_url_request_info.h
+++ b/ppapi/c/ppb_url_request_info.h
@@ -16,8 +16,8 @@ struct PP_Var;
 
 /**
  * @file
- * This file defines the PPB_URLRequestInfo API for creating and manipulating
- * URL requests. This API is used in conjunction with PPB_URLLoader.
+ * This file defines the <code>PPB_URLRequestInfo</code> API for creating and
+ * manipulating URL requests.
  */
 
 /**
@@ -29,12 +29,12 @@ struct PP_Var;
  * This enumeration contains properties that can be set on a URL request.
  */
 typedef enum {
-  /** This corresponds to a string (PP_VARTYPE_STRING). */
+  /** This corresponds to a string (<code>PP_VARTYPE_STRING</code>). */
   PP_URLREQUESTPROPERTY_URL,
 
   /**
-   * This corresponds to a string (PP_VARTYPE_STRING); either POST or GET.
-   * Refer to the
+   * This corresponds to a string (<code>PP_VARTYPE_STRING</code>); either
+   * POST or GET. Refer to the
    * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html">HTTP
    * Methods</a> documentation for further information.
    *
@@ -42,65 +42,72 @@ typedef enum {
   PP_URLREQUESTPROPERTY_METHOD,
 
   /**
-   * This corresponds to a string (PP_VARTYPE_STRING); \n delimited.
-   * Refer to the
+   * This corresponds to a string (<code>PP_VARTYPE_STRING</code>); \n
+   * delimited. Refer to the
    * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html"Header
    * Field Definitions</a> documentaiton for further information.
    */
   PP_URLREQUESTPROPERTY_HEADERS,
 
   /**
-   * This corresponds to a PP_Bool (PP_VARTYPE_BOOL; default=PP_FALSE).
-   * Set this value to PP_TRUE if you want to download the data to a file. Use
-   * PPB_URLLoader.FinishStreamingToFile() to complete the download.
+   * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
+   * default=<code>PP_FALSE</code>).
+   * Set this value to <code>PP_TRUE</code> if you want to download the data
+   * to a file. Use PPB_URLLoader.FinishStreamingToFile() to complete the
+   * download.
    */
   PP_URLREQUESTPROPERTY_STREAMTOFILE,
 
   /**
-   * This corresponds to a PP_Bool (PP_VARTYPE_BOOL; default=PP_TRUE).
-   * Set this value to PP_FALSE if you want to use
+   * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
+   * default=<code>PP_TRUE</code>).
+   * Set this value to <code>PP_FALSE</code> if you want to use
    * PPB_URLLoader.FollowRedirects() to follow the redirects only after
    * examining redirect headers.
    */
   PP_URLREQUESTPROPERTY_FOLLOWREDIRECTS,
 
   /**
-   * This corresponds to a PP_Bool (PP_VARTYPE_BOOL; default=PP_FALSE).
-   * Set this value to PP_TRUE if you want to be able to poll the download
-   * progress using PPB_URLLoader.GetDownloadProgress().
+   * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
+   * default=<code>PP_FALSE</code>).
+   * Set this value to <code>PP_TRUE</code> if you want to be able to poll the
+   * download progress using PPB_URLLoader.GetDownloadProgress().
    */
   PP_URLREQUESTPROPERTY_RECORDDOWNLOADPROGRESS,
 
   /**
-   * This corresponds to a PP_Bool (default=PP_FALSE).
-   * Set this value to PP_TRUE if you want to be able to poll the upload
-   * progress using PPB_URLLoader.GetUplaodProgress().
+   * This corresponds to a <code>PP_Bool (default=<code>PP_FALSE</code>).
+   * Set this value to <code>PP_TRUE</code> if you want to be able to poll the
+   * upload progress using PPB_URLLoader.GetUplaodProgress().
    */
   PP_URLREQUESTPROPERTY_RECORDUPLOADPROGRESS,
 
   /**
-   * This corresponds to a string (PP_VARTYPE_STRING) or may be undefined
-   * (PP_VARTYPE_UNDEFINED; default).
+   * This corresponds to a string (<code>PP_VARTYPE_STRING)</code> or may be
+   * undefined (<code>PP_VARTYPE_UNDEFINED</code>; default).
    * Set it to a string to set a custom referrer (if empty, the referrer header
    * will be omitted), or to undefined to use the default referrer. Only loaders
    * with universal access (only available on trusted implementations) will
-   * accept URLRequestInfo objects that try to set a custom referrer; if given
-   * to a loader without universal access, PP_ERROR_BADARGUMENT will result.
+   * accept <code>URLRequestInfo</code> objects that try to set a custom
+   * referrer; if given to a loader without universal access,
+   * <code>PP_ERROR_BADARGUMENT</code> will result.
    */
   PP_URLREQUESTPROPERTY_CUSTOMREFERRERURL,
 
   /**
-   * This corresponds to a PP_Bool (PP_VARTYPE_BOOL; default=PP_FALSE).
-   * Whether cross-origin requests are allowed. Cross-origin requests are made
-   * using the CORS (Cross-Origin Resource Sharing) algorithm to check whether
-   * the request should be allowed. For the complete CORS algorithm, refer to
+   * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
+   * default=<code>PP_FALSE</code>). Whether cross-origin requests are allowed.
+   * Cross-origin requests are made using the CORS (Cross-Origin Resource
+   * Sharing) algorithm to check whether the request should be allowed. For the
+   * complete CORS algorithm, refer to
    * the <a href="http://www.w3.org/TR/access-control">Cross-Origin Resource
    * Sharing</a> documentation.
    */
   PP_URLREQUESTPROPERTY_ALLOWCROSSORIGINREQUESTS,
 
   /**
-   * This corresponds to a PP_Bool (PP_VARTYPE_BOOL; default=PP_FALSE).
+   * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
+   * default=<code>PP_FALSE</code>).
    * Whether HTTP credentials are sent with cross-origin requests. If false,
    * no credentials are sent with the request and cookies are ignored in the
    * response. If the request is not cross-origin, this property is ignored.
@@ -108,41 +115,41 @@ typedef enum {
   PP_URLREQUESTPROPERTY_ALLOWCREDENTIALS,
 
   /**
-   * This corresponds to a string (PP_VARTYPE_STRING) or may be undefined
-   * (PP_VARTYPE_UNDEFINED; default).
+   * This corresponds to a string (<code>PP_VARTYPE_STRING</code>) or may be
+   * undefined (<code>PP_VARTYPE_UNDEFINED</code>; default).
    * Set it to a string to set a custom content-transfer-encoding header (if
-   * empty, that header will be omitted), or to undefined to use the default (if
-   * any). Only loaders with universal access (only available on trusted
-   * implementations) will accept URLRequestInfo objects that try to set a
-   * custom content transfer encoding; if given to a loader without universal
-   * access, PP_ERROR_BADARGUMENT will result.
+   * empty, that header will be omitted), or to undefined to use the default
+   * (if any). Only loaders with universal access (only available on trusted
+   * implementations) will accept <code>URLRequestInfo</code> objects that try
+   * to set a custom content transfer encoding; if given to a loader without
+   * universal access, <code>PP_ERROR_BADARGUMENT</code> will result.
    */
   PP_URLREQUESTPROPERTY_CUSTOMCONTENTTRANSFERENCODING,
 
   /**
-   * This corresponds to an integer (PP_VARTYPE_INT32); default is not defined
-   * and is set by the browser, possibly depending on system capabilities.
-   * Set it to an integer to set an upper threshold for the prefetched buffer
-   * of an asynchronous load. When exceeded, the browser will defer loading
-   * until PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD is hit, at which
-   * time it will begin prefetching again.
-   * When setting this property,
-   * PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD must also be set.
-   * Behavior is undefined if the former is <= the latter.
+   * This corresponds to an integer (<code>PP_VARTYPE_INT32</code>); default
+   * is not defined and is set by the browser, possibly depending on system
+   * capabilities. Set it to an integer to set an upper threshold for the
+   * prefetched buffer of an asynchronous load. When exceeded, the browser will
+   * defer loading until
+   * <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> is hit,
+   * at which time it will begin prefetching again. When setting this property,
+   * <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> must also
+   * be set. Behavior is undefined if the former is <= the latter.
    */
   PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD,
 
   /**
-   * This corresponds to an integer (PP_VARTYPE_INT32); default is not defined
-   * and is set by the browser to a value appropriate for the default
-   * PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD.
+   * This corresponds to an integer (<code>PP_VARTYPE_INT32</code>); default is
+   * not defined and is set by the browser to a value appropriate for the
+   * default <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code>.
    * Set it to an integer to set a lower threshold for the prefetched buffer
    * of an asynchronous load. When reached, the browser will resume loading if
-   * If PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD had previously been
-   * reached.
+   * If <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> had
+   * previously been reached.
    * When setting this property,
-   * PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD must also be set.
-   * Behavior is undefined if the former is >= the latter.
+   * <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code> must also
+   * be set. Behavior is undefined if the former is >= the latter.
    */
   PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERTHRESHOLD
 } PP_URLRequestProperty;
@@ -161,57 +168,64 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_URLRequestProperty, 4);
  */
 
 /**
- * The PPB_URLRequestInfo interface contains pointers to functions for creating
- * and handling URL requests. Refer to PPB_URLLoader for further information.
+ * The <code>PPB_URLRequestInfo</code> interface is used to create
+ * and handle URL requests. This API is used in conjunction with
+ * <code>PPB_URLLoader</code>. Refer to <code>PPB_URLLoader for further
+ * information.
  */
 struct PPB_URLRequestInfo {
   /**
-   * Create is a pointer to a function that creates a new URLRequestInfo
-   * object.
+   * Create() creates a new <code>URLRequestInfo</code> object.
+   *
+   * @param[in] instance A <code>PP_Instance</code> indentifying one instance
+   * of a module.
    *
-   * @param[in] instance A PP_Instance indentifying one instance of a module.
-   * @return A PP_Resource identifying the URLRequestInfo if successful, 0 if
-   * the instance is invalid.
+   * @return A <code>PP_Resource</code> identifying the
+   * <code>URLRequestInfo</code> if successful, 0 if the instance is invalid.
    */
   PP_Resource (*Create)(PP_Instance instance);
 
   /**
-   * IsURLRequestInfo is a pointer to a function that determines if a resource
-   * is a URLRequestInfo.
+   * IsURLRequestInfo() determines if a resource is a
+   * <code>URLRequestInfo</code>.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a
+   * <code>URLRequestInfo</code>.
    *
-   * @param[in] resource A PP_Resource corresponding to a URLRequestInfo.
-   * @return PP_TRUE if the resource is a URLRequestInfo,
-   * PP_FALSE if the resource is invalid or some type other than
-   * URLRequestInfo.
+   * @return <code>PP_TRUE</code> if the resource is a
+   * <code>URLRequestInfo</code>, <code>PP_FALSE</code> if the resource is
+   * invalid or some type other than <code>URLRequestInfo</code>.
    */
   PP_Bool (*IsURLRequestInfo)(PP_Resource resource);
 
   /**
-   * SetProperty is a pointer to a function that sets a request property. The
-   * value of the property must be the correct type according to the property
-   * being set.
+   * SetProperty() sets a request property. The value of the property must be
+   * the correct type according to the property being set.
    *
-   * @param[in] request A PP_Resource corresponding to a URLRequestInfo.
-   * @param[in] property A PP_URLRequestProperty identifying the
+   * @param[in] request A <code>PP_Resource</code> corresponding to a
+   * <code>URLRequestInfo</code>.
+   * @param[in] property A <code>PP_URLRequestProperty</code> identifying the
    * property to set.
-   * @param[in] value A PP_Var containing the property value.
-   * @return PP_TRUE if successful, PP_FALSE if any of the
-   * parameters are invalid.
+   * @param[in] value A <code>PP_Var</code> containing the property value.
+   *
+   * @return <code>PP_TRUE</code> if successful, <code>PP_FALSE</code> if any
+   * of the parameters are invalid.
    */
   PP_Bool (*SetProperty)(PP_Resource request,
                          PP_URLRequestProperty property,
                          struct PP_Var value);
 
   /**
-   * AppendDataToBody is a pointer to a function that appends data to the
-   * request body. A Content-Length request header will be automatically
-   * generated.
+   * AppendDataToBody() appends data to the request body. A Content-Length
+   * request header will be automatically generated.
    *
-   * @param[in] request A PP_Resource corresponding to a URLRequestInfo.
+   * @param[in] request A <code>PP_Resource</code> corresponding to a
+   * <code>URLRequestInfo</code>.
    * @param[in] data A pointer to a buffer holding the data.
    * @param[in] len The length, in bytes, of the data.
-   * @return PP_TRUE if successful, PP_FALSE if any of the
-   * parameters are invalid.
+   *
+   * @return <code>PP_TRUE</code> if successful, <code>PP_FALSE</code> if any
+   * of the parameters are invalid.
    *
    *
    */
@@ -220,25 +234,27 @@ struct PPB_URLRequestInfo {
                               uint32_t len);
 
   /**
-   * AppendFileToBody is a pointer to a function used to append a file, to be
-   * uploaded, to the request body. A content-length request header will be
-   * automatically generated.
+   * AppendFileToBody() appends a file, to be uploaded, to the request body.
+   * A content-length request header will be automatically generated.
    *
-   * @param[in] request A PP_Resource corresponding to a URLRequestInfo.
-   * @param[in] file_ref A PP_Resource containing the file reference.
+   * @param[in] request A <code>PP_Resource</code> corresponding to a
+   * <code>URLRequestInfo</code>.
+   * @param[in] file_ref A <code>PP_Resource</code> containing the file
+   * reference.
    * @param[in] start_offset An optional starting point offset within the
    * file.
    * @param[in] number_of_bytes An optional number of bytes of the file to
-   * be included. If number_of_bytes is -1, then the sub-range to upload
-   * extends to the end of the file.
+   * be included. If <code>number_of_bytes</code> is -1, then the sub-range
+   * to upload extends to the end of the file.
    * @param[in] expected_last_modified_time An optional (non-zero) last
    * modified time stamp used to validate that the file was not modified since
    * the given time before it was uploaded. The upload will fail with an error
-   * code of PP_ERROR_FILECHANGED if the file has been modified since the given
-   * time. If expected_last_modified_time is 0, then no validation is
-   * performed.
-   * @return PP_TRUE if successful, PP_FALSE if any of the
-   * parameters are invalid.
+   * code of <code>PP_ERROR_FILECHANGED</code> if the file has been modified
+   * since the given time. If <code>expected_last_modified_time</code> is 0,
+   * then no validation is performed.
+   *
+   * @return <code>PP_TRUE</code> if successful, <code>PP_FALSE</code> if any
+   * of the parameters are invalid.
    */
   PP_Bool (*AppendFileToBody)(PP_Resource request,
                               PP_Resource file_ref,
diff --git a/ppapi/c/ppb_url_response_info.h b/ppapi/c/ppb_url_response_info.h
index 6956a36..cf8403d 100644
--- a/ppapi/c/ppb_url_response_info.h
+++ b/ppapi/c/ppb_url_response_info.h
@@ -12,7 +12,7 @@
 
 /**
  * @file
- * This file defines the PPB_URLResponseInfo API for examining URL
+ * This file defines the <code>PPB_URLResponseInfo</code> API for examining URL
  * responses.
  */
 
@@ -29,22 +29,25 @@
 // full URL in the response corresponds to the relative URL in the original
 // request).
 typedef enum {
-  /** This corresponds to a string (PP_VARTYPE_STRING). */
+  /** This corresponds to a string (<code>PP_VARTYPE_STRING</code>). */
   PP_URLRESPONSEPROPERTY_URL,
 
-  /** This corresponds to a string (PP_VARTYPE_STRING).*/
+  /** This corresponds to a string (<code>PP_VARTYPE_STRING</code>).*/
   PP_URLRESPONSEPROPERTY_REDIRECTURL,
 
-  /** This corresponds to a string (PP_VARTYPE_STRING).*/
+  /** This corresponds to a string (<code>PP_VARTYPE_STRING</code>).*/
   PP_URLRESPONSEPROPERTY_REDIRECTMETHOD,
 
-  /** This corresponds to an int32 (PP_VARETYPE_INT32)*/
+  /** This corresponds to an int32 (<code>PP_VARETYPE_INT32</code>)*/
   PP_URLRESPONSEPROPERTY_STATUSCODE,
 
-  /** This corresponds to a string (PP_VARTYPE_STRING).*/
+  /** This corresponds to a string (<code>PP_VARTYPE_STRING</code>).*/
   PP_URLRESPONSEPROPERTY_STATUSLINE,
 
-  /** This corresponds to a string(PP_VARTYPE_STRING), \n delimited */
+  /**
+   * This corresponds to a string(<code>PP_VARTYPE_STRING</code>),
+   * \n delimited
+   */
   PP_URLRESPONSEPROPERTY_HEADERS
 } PP_URLResponseProperty;
 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_URLResponseProperty, 4);
@@ -62,47 +65,53 @@ PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_URLResponseProperty, 4);
  */
 
 /**
- * The PPB_URLResponseInfo interface contains pointers to functions for
- * examining URL responses. Refer to PPB_URLLoader for further
+ * The PPB_URLResponseInfo interface contains APIs for
+ * examining URL responses. Refer to <code>PPB_URLLoader</code> for further
  * information.
  */
 struct PPB_URLResponseInfo {
 
   /**
-   * IsURLResponseInfo is a pointer to a function that determines if a
-   * response is a URLResponseInfo.
+   * IsURLResponseInfo() determines if a response is a
+   * <code>URLResponseInfo</code>.
+   *
+   * @param[in] resource A <code>PP_Resource</code> corresponding to a
+   * <code>URLResponseInfo</code>.
    *
-   * @param[in] resource A PP_Resource corresponding to a URLResponseInfo.
-   * @return PP_TRUE if the resource is a URLResponseInfo,
-   * PP_FALSE if the resource is invalid or some type other than
-   * URLResponseInfo.
+   * @return <code>PP_TRUE</code> if the resource is a
+   * <code>URLResponseInfo</code>, <code>PP_FALSE</code> if the resource is
+   * invalid or some type other than <code>URLResponseInfo</code>.
    */
   PP_Bool (*IsURLResponseInfo)(PP_Resource resource);
 
   /**
-   * GetProperty is a pointer to a function that gets a response property.
+   * GetProperty() gets a response property.
    *
-   * @param[in] request A PP_Resource corresponding to a URLResponseInfo.
-   * @param[in] property A PP_URLResponseProperty identifying the type of
-   * property in the response.
-   * @return A PP_Var containing the response property value if successful,
-   * PP_VARTYPE_VOID if an input parameter is invalid.
+   * @param[in] request A <code>PP_Resource</code> corresponding to a
+   * <code>URLResponseInfo</code>.
+   * @param[in] property A <code>PP_URLResponseProperty</code> identifying
+   * the type of property in the response.
+   *
+   * @return A <code>PP_Var</code> containing the response property value if
+   * successful, <code>PP_VARTYPE_VOID</code> if an input parameter is invalid.
    */
   struct PP_Var (*GetProperty)(PP_Resource response,
                                PP_URLResponseProperty property);
 
   /**
-   * GetBodyAsFileRef is a pointer to a function that returns a FileRef
-   * pointing to the file containing the response body.  This
-   * is only valid if PP_URLREQUESTPROPERTY_STREAMTOFILE was set on the
-   * URLRequestInfo used to produce this response.  This file remains valid
-   * until the URLLoader associated with this URLResponseInfo is closed or
-   * destroyed.
+   * GetBodyAsFileRef() returns a FileRef pointing to the file containing the
+   * response body.  This is only valid if
+   * <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set on the
+   * <code>URLRequestInfo</code> used to produce this response.  This file
+   * remains valid until the <code>URLLoader</code> associated with this
+   * <code>URLResponseInfo is closed or destroyed.
+   *
+   * @param[in] request A <code>PP_Resource</code> corresponding to a
+   * <code>URLResponseInfo</code>.
    *
-   * @param[in] request A PP_Resource corresponding to a URLResponseInfo.
-   * @return A PP_Resource corresponding to a FileRef if successful, 0 if
-   * PP_URLREQUESTPROPERTY_STREAMTOFILE was not requested or if the URLLoader
-   * has not been opened yet.
+   * @return A <code>PP_Resource</code> corresponding to a FileRef if
+   * successful, 0 if <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was not
+   * requested or if the <code>URLLoader</code> has not been opened yet.
    */
   PP_Resource (*GetBodyAsFileRef)(PP_Resource response);
 };
diff --git a/ppapi/c/ppb_var.h b/ppapi/c/ppb_var.h
index 2fa4ec5..6f7ce0b 100644
--- a/ppapi/c/ppb_var.h
+++ b/ppapi/c/ppb_var.h
@@ -18,7 +18,7 @@
 
 /**
  * @file
- * This file defines the PPB_Var struct.
+ * This file defines the <code>PPB_Var</code> struct.
  */
 
 /**
@@ -31,51 +31,69 @@
  */
 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.
+   * AddRef() 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.
+   *
+   * @param[in] var A <code>PP_Var</code> that will have a reference added.
    */
   void (*AddRef)(struct PP_Var var);
 
   /**
-   * Removes a reference to given var, deleting it if the internal refcount
-   * becomes 0. If the given var is not a refcounted object, this function will
-   * do nothing so you can always call it no matter what the type.
+   * Release() removes a reference to given var, deleting it if the internal
+   * reference count becomes 0. If the given var is not a refcounted object,
+   * this function will do nothing so you can always call it no matter what
+   * the type.
+   *
+   * @param[in] var A <code>PP_Var</code> that will have a reference removed.
    */
   void (*Release)(struct PP_Var var);
 
   /**
-   * Creates a string var from a string. The string must be encoded in valid
-   * UTF-8 and is NOT NULL-terminated, the length must be specified in |len|.
-   * It is an error if the string is not valid UTF-8.
+   * VarFromUtf8() creates a string var from a string. The string must be
+   * encoded in valid UTF-8 and is NOT NULL-terminated, the length must be
+   * specified in <code>len</code>. It is an error if the string is not
+   * valid UTF-8.
    *
-   * If the length is 0, the |data| pointer will not be dereferenced and may
-   * be NULL. Note, however, that if you do this, the "NULL-ness" will not be
-   * preserved, as VarToUtf8 will never return NULL on success, even for empty
-   * strings.
+   * If the length is 0, the <code>*data</code> pointer will not be dereferenced
+   * and may be <code>NULL</code>. Note, however if length is 0, the
+   * "NULL-ness" will not be preserved, as <code>VarToUtf8</code> will never
+   * return <code>NULL</code> on success, even for empty strings.
    *
    * The resulting object will be a refcounted string object. It will be
-   * AddRef()ed for the caller. When the caller is done with it, it should be
-   * Release()d.
+   * AddRef'ed for the caller. When the caller is done with it, it should be
+   * Released.
    *
    * On error (basically out of memory to allocate the string, or input that
    * is not valid UTF-8), this function will return a Null var.
+   *
+   * @param[in] module A PP_Module uniquely identifying the module or .nexe.
+   * @param[in] data A string
+   * @param[in] len The length of the string.
+   *
+   * @return A <code>PP_Var</code> structure containing a reference counted
+   * string object.
    */
   struct PP_Var (*VarFromUtf8)(PP_Module module,
                                const char* data, uint32_t len);
 
   /**
-   * Converts a string-type var to a char* encoded in UTF-8. This string is NOT
-   * NULL-terminated. The length will be placed in |*len|. If the string is
-   * valid but empty the return value will be non-NULL, but |*len| will still
-   * be 0.
+   * VarToUtf8() converts a string-type var to a char* encoded in UTF-8. This
+   * string is NOT NULL-terminated. The length will be placed in
+   * <code>*len</code>. If the string is valid but empty the return value will
+   * be non-NULL, but <code>*len</code> will still be 0.
    *
-   * If the var is not a string, this function will return NULL and |*len| will
-   * be 0.
+   * If the var is not a string, this function will return NULL and
+   * <code>*len</code> will be 0.
    *
    * The returned buffer will be valid as long as the underlying var is alive.
-   * If the plugin frees its reference, the string will be freed and the pointer
-   * will be to random memory.
+   * If the instance frees its reference, the string will be freed and the
+   * pointer will be to arbitrary memory.
+   *
+   * @param[in] var A PP_Var struct containing a string-type var.
+   * @param[in,out] len A pointer to the length of the string-type var.
+   *
+   * @return A char* encoded in UTF-8.
    */
   const char* (*VarToUtf8)(struct PP_Var var, uint32_t* len);
 };
diff --git a/ppapi/c/ppp.h b/ppapi/c/ppp.h
index 3d0af05..7b34ee8 100644
--- a/ppapi/c/ppp.h
+++ b/ppapi/c/ppp.h
@@ -40,17 +40,16 @@ extern "C" {
  * PPP_InitializeModule() is the entry point for a module and is called by the
  * browser when your module loads. Your code must implement this function.
  *
- * Failure indicates to the browser that this plugin can not be used. In this
- * case, the plugin will be unloaded and ShutdownModule will NOT be called.
+ * Failure indicates to the browser that this module can not be used. In this
+ * case, the module will be unloaded and ShutdownModule will NOT be called.
  *
  * @param[in] module A handle to your module. Generally you should store this
  * value since it will be required for other API calls.
- *
  * @param[in] get_browser_interface A pointer to the function that you can
  * use to query for browser interfaces. Generally you should store this value
  * for future use.
  *
- * @return PP_OK on success. Any other value on failure.
+ * @return <code>PP_OK</code> on success. Any other value on failure.
 */
 PP_EXPORT int32_t PPP_InitializeModule(PP_Module module,
                                        PPB_GetInterface get_browser_interface);
@@ -67,10 +66,10 @@ PP_EXPORT int32_t PPP_InitializeModule(PP_Module module,
  * PPP_ShutdownModule() is <strong>sometimes</strong> called before the module
  * is unloaded. It is not recommended that you implement this function.
  *
- * There is no practical use of this function for third party plugins. Its
+ * There is no practical use of this function for third party modules. Its
  * existence is because of some internal use cases inside Chrome.
  *
- * Since your plugin runs in a separate process, there's no need to free
+ * Since your module runs in a separate process, there's no need to free
  * allocated memory. There is also no need to free any resources since all of
  * resources associated with an instance will be force-freed when that instance
  * is deleted. Moreover, this function will not be called when Chrome does
@@ -90,14 +89,14 @@ PP_EXPORT void PPP_ShutdownModule();
  * PPP_GetInterface() is called by the browser to query the module for
  * interfaces it supports.
  *
- * Your module must implement the PPP_Instance interface or it will be
- * unloaded. Other interfaces are optional.
+ * Your module must implement the <code>PPP_Instance</code> interface or it
+ * will be unloaded. Other interfaces are optional.
  *
  * @param[in] interface_name A pointer to a "PPP" (plugin) interface name.
  * Interface names are null-terminated ASCII strings.
  *
- * @return A pointer for the interface or NULL if the interface is not
- * supported.
+ * @return A pointer for the interface or <code>NULL</code> if the interface is
+ * not supported.
  */
 PP_EXPORT const void* PPP_GetInterface(const char* interface_name);
 /**
diff --git a/ppapi/c/ppp_messaging.h b/ppapi/c/ppp_messaging.h
index 5441a50..29a7976 100644
--- a/ppapi/c/ppp_messaging.h
+++ b/ppapi/c/ppp_messaging.h
@@ -24,27 +24,29 @@ struct PP_Var;
  */
 
 /**
- * The PPP_Messaging interface contains pointers to functions that you must
- * implement to handle postMessage events on the associated DOM element.
+ * The <code>PPP_Messaging</code> interface contains pointers to functions
+ * that you must implement to handle postMessage events on the associated
+ * DOM element.
  */
 struct PPP_Messaging {
   /**
-   * HandleMessage is a pointer to a function that the browser calls when
-   * PostMessage() is invoked on the DOM element for the module instance in
-   * JavaScript. Note that PostMessage() in the JavaScript interface is
-   * asynchronous, meaning JavaScript execution will not be blocked while
-   * HandleMessage() is processing the message.
+   * HandleMessage() is a function that the browser calls when PostMessage()
+   * is invoked on the DOM element for the module instance in JavaScript. Note
+   * that PostMessage() in the JavaScript interface is asynchronous, meaning
+   * JavaScript execution will not be blocked while HandleMessage() is
+   * processing the message.
    *
-   * @param[in] instance A PP_Instance indentifying one instance of a module.
-   * @param[in] message A PP_Var containing the data to be sent to JavaScript.
-   * Message can have an int32_t, double, bool, or string value (objects
-   * are not supported).
+   * @param[in] instance A <code>PP_Instance</code> indentifying one instance
+   * of a module.
+   * @param[in] message A <code>PP_Var</code> containing the data to be sent
+   * to JavaScript. Message can have an int32_t, double, bool, or string value
+   * (objects are not supported).
    *
    * <strong>Example:</strong>
    *
-   * The following JavaScript code invokes HandleMessage, passing the module
-   * instance on which it was invoked, with <code>message</code> being a
-   * string PP_Var containing "Hello world!"
+   * The following JavaScript code invokes <code>HandleMessage</code>, passing
+   * the module instance on which it was invoked, with <code>message</code>
+   * being a string <code>PP_Var</code> containing "Hello world!"
    *
    * @code
    *