Small changes such as spacing and adding [in/out] identifiers after @params.

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

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

13 files changed, 276 insertions, 107 deletions

diff --git a/ppapi/cpp/audio.h b/ppapi/cpp/audio.h
index cc98e56..48bb40e 100644
--- a/ppapi/cpp/audio.h
+++ b/ppapi/cpp/audio.h
@@ -64,9 +64,13 @@ class Audio : public Resource {
   const AudioConfig& config() const { return config_; }
 
   /// StartPlayback() starts playback of audio.
+  ///
+  /// @return true if successful, otherwise false.
   bool StartPlayback();
 
   /// StopPlayback stops playback of audio.
+  ///
+  /// @return true if successful, otherwise false.
   bool StopPlayback();
 
  private:
diff --git a/ppapi/cpp/core.h b/ppapi/cpp/core.h
index 0b0f3ee..5c3ad77e 100644
--- a/ppapi/cpp/core.h
+++ b/ppapi/cpp/core.h
@@ -51,7 +51,7 @@ class Core {
 
   /// GetTimeTicks() returns the "tick time" according to the browser.
   /// This clock is used by the browser when passing some event times to the
-  /// plugin (for example, using the
+  /// module (for example, 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 change if the user changes their computer clock.
@@ -67,7 +67,7 @@ class Core {
   /// 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
+  /// callback. Many applications won't need this, but it allows a module to
   /// emulate calls of some callbacks which do use this value.
   ///
   /// <strong>Note:</strong> CallOnMainThread(), even when used from the main
@@ -94,8 +94,8 @@ class Core {
   /// This function is useful for implementing sanity checks, and deciding if
   /// dispatching using CallOnMainThread() is required.
   ///
-  /// @return A bool containing true if the current thread is
-  /// the main pepper thread, otherwise false.
+  /// @return true if the current thread is the main pepper thread, otherwise
+  /// false.
   bool IsMainThread();
 
  private:
diff --git a/ppapi/cpp/graphics_2d.h b/ppapi/cpp/graphics_2d.h
index 52e0380..75583ca 100644
--- a/ppapi/cpp/graphics_2d.h
+++ b/ppapi/cpp/graphics_2d.h
@@ -63,6 +63,7 @@ class Graphics2D : public Resource {
   /// of this 2D graphics context.
   ///
   /// @param[in] other An other 2D graphics context.
+  ///
   /// @return A new Graphics2D context.
   Graphics2D& operator=(const Graphics2D& other);
 
diff --git a/ppapi/cpp/image_data.h b/ppapi/cpp/image_data.h
index b472a85..e4159c0 100644
--- a/ppapi/cpp/image_data.h
+++ b/ppapi/cpp/image_data.h
@@ -51,10 +51,9 @@ class ImageData : public Resource {
   ///
   /// @param[in] format A PP_ImageDataFormat containing desired image format.
   /// PP_ImageDataFormat is an enumeration of the different types of
-  /// image data formats. Refer to the
-  /// <a href="/chrome/nativeclient/docs/reference/pepperc/
-  /// ppb__image__data_8h.html"><code>ppb_image_data.h</code></a> for further
-  /// information.
+  /// image data formats. Refer to
+  /// <a href="../pepperc/ppb__image__data_8h.html">
+  /// <code>ppb_image_data.h</code></a> for further information.
   ///
   /// @param[in] size A pointer to a <code>Size</code> containing the image
   /// size.
diff --git a/ppapi/cpp/input_event.h b/ppapi/cpp/input_event.h
index 2b66527..f634cb9 100644
--- a/ppapi/cpp/input_event.h
+++ b/ppapi/cpp/input_event.h
@@ -10,6 +10,9 @@
 #include "ppapi/c/ppb_input_event.h"
 #include "ppapi/cpp/resource.h"
 
+/// @file
+/// This file defines the API used to handle mouse and keyboard input events.
+
 namespace pp {
 
 class FloatPoint;
@@ -17,12 +20,16 @@ class Instance;
 class Point;
 class Var;
 
-/// Represents an input event resource. Normally you will get passed this
-/// object through the HandleInputEvent on the Instance object.
+/// This class represents an input event resource. Normally you will get passed
+/// this object through the HandleInputEvent() function on the
+/// <code>Instance</code> object.
 ///
 /// Typically you would check the type of the event and then create the
 /// appropriate event-specific object to query the properties.
 ///
+/// <strong>Example:</strong>
+/// @code
+///
 /// bool MyInstance::HandleInputEvent(const pp::InputEvent& event) {
 ///   switch (event.GetType()) {
 ///     case PP_INPUTEVENT_TYPE_MOUSE_DOWN {
@@ -32,55 +39,90 @@ class Var;
 ///     default:
 ///       return false;
 /// }
+///
+/// @endcode
 class InputEvent : public Resource {
  public:
   /// Default constructor that creates an is_null() InputEvent object.
   InputEvent();
 
-  /// Constructs an input event from the given input event resource ID. The
-  /// InputEvent object will be is_null() if the given resource is not a valid
-  /// input event.
+  /// This constructor constructs an input event from the provided input event
+  /// resource ID. The InputEvent object will be is_null() if the given
+  /// resource is not a valid input event.
+  ///
+  /// @param[in] input_event_resource A input event resource ID.
   explicit InputEvent(PP_Resource input_event_resource);
 
   ~InputEvent();
 
-  /// Returns the type of input event for the given input event resource.
-  /// This is valid for all input events. Returns PP_INPUTEVENT_TYPE_UNDEFINED
-  /// if the resource is invalid.
+  /// GetType() returns the type of input event for this input event
+  /// object.
+  ///
+  /// @return A <code>PP_InputEvent_Type</code> if successful,
+  /// PP_INPUTEVENT_TYPE_UNDEFINED if the resource is invalid.
   PP_InputEvent_Type GetType() const;
 
-  /// Returns the time that the event was generated. This will be before the
-  /// current time since processing and dispatching the event has some overhead.
-  /// Use this value to compare the times the user generated two events without
-  /// being sensitive to variable processing time.
+  /// GetTimeStamp() returns the time that the event was generated. The time
+  /// will be before the current time since processing and dispatching the
+  /// event has some overhead. Use this value to compare the times the user
+  /// generated two events without being sensitive to variable processing time.
   ///
   /// The return value is in time ticks, which is a monotonically increasing
   /// clock not related to the wall clock time. It will not change if the user
   /// changes their clock or daylight savings time starts, so can be reliably
   /// used to compare events. This means, however, that you can't correlate
   /// event times to a particular time of day on the system clock.
+  ///
+  /// @return A <code>PP_TimeTicks</code> containing the time the event was
+  /// generated.
   PP_TimeTicks GetTimeStamp() const;
 
-  /// Returns a bitfield indicating which modifiers were down at the time of
-  /// the event. This is a combination of the flags in the
-  /// PP_InputEvent_Modifier enum.
+  /// GetModifiers() returns a bitfield indicating which modifiers were down
+  /// at the time of the event. This is a combination of the flags in the
+  /// <code>PP_InputEvent_Modifier</code> enum.
   ///
   /// @return The modifiers associated with the event, or 0 if the given
   /// resource is not a valid event resource.
   uint32_t GetModifiers() const;
 };
 
+/// This class handles mouse events.
 class MouseInputEvent : public InputEvent {
  public:
   /// Constructs an is_null() mouse input event object.
   MouseInputEvent();
 
-  /// Constructs a mouse input event object from the given generic input
-  /// event. If the given event is itself is_null() or is not a mouse input
-  /// event, the mouse object will be is_null().
+  /// This constructor constructs a mouse input event object from the provided
+  /// generic input event. If the given event is itself is_null() or is not
+  /// a mouse input event, the mouse object will be is_null().
+  ///
+  /// @param event An <code>InputEvent</code>.
   explicit MouseInputEvent(const InputEvent& event);
 
-  /// Manually constructs a mouse event from the given parameters.
+  /// This constructor manually constructs a mouse event from the provided
+  /// parameters.
+  ///
+  /// @param[in] instance The instance for which this event occured.
+  ///
+  /// @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
+  /// input event.
+  ///
+  /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
+  /// when the event occured.
+  ///
+  /// @param[in] modifiers A bit field combination of the
+  /// <code>PP_InputEvent_Modifier</code> flags.
+  ///
+  /// @param[in] mouse_button The button that changed for mouse down or up
+  /// events. This value will be <code>PP_EVENT_MOUSEBUTTON_NONE</code> for
+  /// mouse move, enter, and leave events.
+  ///
+  /// @param[in] mouse_position A <code>Point</code> containing the x and y
+  /// position of the mouse when the eent occurred.
+  ///
+  /// @param[in] click_count
+  /// TODO(brettw) figure out exactly what this means.
+  ///
   MouseInputEvent(Instance* instance,
                   PP_InputEvent_Type type,
                   PP_TimeTicks time_stamp,
@@ -89,15 +131,15 @@ class MouseInputEvent : public InputEvent {
                   const Point& mouse_position,
                   int32_t click_count);
 
-  /// Returns the mouse position for a mouse input event.
+  /// GetButton() returns the mouse position for a mouse input event.
   ///
   /// @return The mouse button associated with mouse down and up events. This
   /// value will be PP_EVENT_MOUSEBUTTON_NONE for mouse move, enter, and leave
   /// events, and for all non-mouse events.
   PP_InputEvent_MouseButton GetButton() const;
 
-  /// Returns the pixel location of a mouse input event. This value is in
-  /// floating-point units to support high-resolution input events.
+  /// GetPostion() returns the pixel location of a mouse input event. This
+  /// value is in floating-point units to support high-resolution input events.
   ///
   /// @return The point associated with the mouse event, relative to the upper-
   /// left of the instance receiving the event. These values can be negative for
@@ -113,12 +155,32 @@ class WheelInputEvent : public InputEvent {
   /// Constructs an is_null() wheel input event object.
   WheelInputEvent();
 
-  /// Constructs a wheel input event object from the given generic input
-  /// event. If the given event is itself is_null() or is not a wheel input
-  /// event, the wheel object will be is_null().
+  /// This constructor constructs a wheel input event object from the
+  /// provided generic input event. If the given event is itself
+  /// is_null() or is not a wheel input event, the wheel object will be
+  /// is_null().
+  ///
+  /// @param[in] A generic input event.
   explicit WheelInputEvent(const InputEvent& event);
 
   /// Constructs a wheel input even from the given parameters.
+  ///
+  /// @param[in] instance The instance for which this event occured.
+  ///
+  /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
+  /// when the event occured.
+  ///
+  /// @param[in] modifiers A bit field combination of the
+  /// <code>PP_InputEvent_Modifier</code> flags.
+  ///
+  /// @param[in] wheel_delta The scroll wheel's horizontal and vertical scroll
+  /// amounts.
+  ///
+  /// @param[in] wheel_ticks The number of "clicks" of the scroll wheel that
+  /// have produced the event.
+  ///
+  /// @param[in] scroll_by_page When true, the user is requesting to scroll
+  /// by pages. When false, the user is requesting to scroll by lines.
   WheelInputEvent(Instance* instance,
                   PP_TimeTicks time_stamp,
                   uint32_t modifiers,
@@ -126,16 +188,11 @@ class WheelInputEvent : public InputEvent {
                   const FloatPoint& wheel_ticks,
                   bool scroll_by_page);
 
-  /// Indicates the amount vertically and horizontally the user has requested
-  /// to scroll by with their mouse wheel. A scroll down or to the right (where
-  /// the content moves up or left) is represented as positive values, and
-  /// a scroll up or to the left (where the content moves down or right) is
-  /// represented as negative values.
-  ///
-  /// The units are either in pixels (when scroll_by_page is false) or pages
-  /// (when scroll_by_page is true). For example, y = -3 means scroll up 3
-  /// pixels when scroll_by_page is false, and scroll up 3 pages when
-  /// scroll_by_page is true.
+  /// GetDelta() returns the amount vertically and horizontally the user has
+  /// requested to scroll by with their mouse wheel. A scroll down or to the
+  /// right (where the content moves up or left) is represented as positive
+  /// values, and a scroll up or to the left (where the content moves down or
+  /// right) is represented as negative values.
   ///
   /// This amount is system dependent and will take into account the user's
   /// preferred scroll sensitivity and potentially also nonlinear acceleration
@@ -145,31 +202,37 @@ class WheelInputEvent : public InputEvent {
   /// only generate integer scroll amounts. But fractional values are also
   /// possible, for example, on some trackpads and newer mice that don't have
   /// "clicks".
+  ///
+  /// @return The vertial and horizontal scroll values. The units are either in
+  /// pixels (when scroll_by_page is false) or pages (when scroll_by_page is
+  /// true). For example, y = -3 means scroll up 3 pixels when scroll_by_page
+  /// is false, and scroll up 3 pages when scroll_by_page is true.
   FloatPoint GetDelta() const;
 
-  /// The number of "clicks" of the scroll wheel that have produced the
-  /// event. The value may have system-specific acceleration applied to it,
-  /// depending on the device. The positive and negative meanings are the same
-  /// as for GetDelta().
+  /// GetTicks() returns the number of "clicks" of the scroll wheel
+  /// that have produced the event. The value may have system-specific
+  /// acceleration applied to it, depending on the device. The positive and
+  /// negative meanings are the same as for GetDelta().
   ///
   /// If you are scrolling, you probably want to use the delta values.  These
   /// tick events can be useful if you aren't doing actual scrolling and don't
   /// want or pixel values. An example may be cycling between different items in
   /// a game.
   ///
-  /// You may receive fractional values for the wheel ticks if the mouse wheel
-  /// is high resolution or doesn't have "clicks". If your program wants
-  /// discrete events (as in the "picking items" example) you should accumulate
+  /// @return The number of "clicks" of the scroll wheel. You may receive
+  /// fractional values for the wheel ticks if the mouse wheel is high
+  /// resolution or doesn't have "clicks". If your program wants discrete
+  /// events (as in the "picking items" example) you should accumulate
   /// fractional click values from multiple messages until the total value
   /// reaches positive or negative one. This should represent a similar amount
   /// of scrolling as for a mouse that has a discrete mouse wheel.
   FloatPoint GetTicks() const;
 
-  // Indicates if the scroll delta x/y indicates pages or lines to
-  // scroll by.
-  //
-  // @return PP_TRUE if the event is a wheel event and the user is scrolling
-  // by pages. PP_FALSE if not or if the resource is not a wheel event.
+  /// GetScrollByPage() indicates if the scroll delta x/y indicates pages or
+  /// lines to scroll by.
+  ///
+  /// @return true if the event is a wheel event and the user is scrolling
+  /// by pages, false if not or if the resource is not a wheel event.
   bool GetScrollByPage() const;
 };
 
@@ -178,12 +241,32 @@ class KeyboardInputEvent : public InputEvent {
   /// Constructs an is_null() keyboard input event object.
   KeyboardInputEvent();
 
-  /// Constructs a keyboard input event object from the given generic input
+  /// Constructs a keyboard input event object from the provided generic input
   /// event. If the given event is itself is_null() or is not a keyboard input
   /// event, the keybaord object will be is_null().
+  ///
+  /// @param[in] event A generic input event.
   explicit KeyboardInputEvent(const InputEvent& event);
 
   /// Constructs a keyboard input even from the given parameters.
+  ///
+  /// @param[in] instance The instance for which this event occured.
+  ///
+  /// @param[in] type A <code>PP_InputEvent_Type</code> identifying the type of
+  /// input event.
+  ///
+  /// @param[in] time_stamp A <code>PP_TimeTicks</code> indicating the time
+  /// when the event occured.
+  ///
+  /// @param[in]  modifiers A bit field combination of the
+  /// <code>PP_InputEvent_Modifier</code> flags.
+  ///
+  /// @param[in] key_code This value reflects the DOM KeyboardEvent
+  /// <code>keyCode</code> field. Chrome populates this with the Windows-style
+  /// Virtual Key code of the key.
+  ///
+  /// @param[in] character_text This value represents the typed character as a
+  /// UTF-8 string.
   KeyboardInputEvent(Instance* instance,
                      PP_InputEvent_Type type,
                      PP_TimeTicks time_stamp,
@@ -191,7 +274,7 @@ class KeyboardInputEvent : public InputEvent {
                      uint32_t key_code,
                      const Var& character_text);
 
-  /// Returns the DOM |keyCode| field for the keyboard event.
+  /// Returns the DOM keyCode field for the keyboard event.
   /// Chrome populates this with the Windows-style Virtual Key code of the key.
   uint32_t GetKeyCode() const;
 
diff --git a/ppapi/cpp/instance.h b/ppapi/cpp/instance.h
index caeb669..6578ea7 100644
--- a/ppapi/cpp/instance.h
+++ b/ppapi/cpp/instance.h
@@ -66,6 +66,8 @@ class Instance {
   /// This function returns the <code>PP_Instance</code> identifying this
   /// object. When using the PPAPI C++ wrappers this is not normally necessary,
   /// but is required when using the lower-level C APIs.
+  ///
+  /// @return A <code>PP_Instance</code> identifying this object.
   PP_Instance pp_instance() const { return pp_instance_; }
 
   /// Init() initializes this instance with the provided arguments. This
@@ -86,7 +88,7 @@ class Instance {
   /// argument values: "nacl_module" and "2".  The indices of these values
   /// match the indices of the corresponding names in <code>argn</code>.
   ///
-  /// @return True on success. Returning false causes the instance to be
+  /// @return true on success. Returning false causes the instance to be
   /// instance to be deleted and no other functions to be called.
   virtual bool Init(uint32_t argc, const char* argn[], const char* argv[]);
 
@@ -177,6 +179,8 @@ class Instance {
   /// Refer to <code>RequestInputEvents</code> and
   /// <code>RequestFilteringInputEvents</code> for further information.
   ///
+  /// @param[in] event The event to handle.
+  ///
   /// @return true if the event was handled, false if not. If you have
   /// registered to filter this class of events by calling
   /// <code>RequestFilteringInputEvents</code>, and you return false,
@@ -213,12 +217,6 @@ class Instance {
   /// JavaScript execution will not be blocked while HandleMessage() is
   /// processing the message.
   ///
-  /// @param[in] message A <code>Var</code> containing the data sent from
-  /// JavaScript. Message can have an int32_t, double, bool, or string value
-  /// (objects are not supported).
-  ///
-  /// \see PostMessage for sending messages to JavaScript.
-  ///
   /// <strong>Example:</strong>
   ///
   /// The following JavaScript code invokes <code>HandleMessage</code>, passing
@@ -236,6 +234,12 @@ class Instance {
   /// </body>
   ///
   /// @endcode
+  ///
+  /// Refer to PostMessage() for sending messages to JavaScript.
+  ///
+  /// @param[in] message A <code>Var</code> containing the data sent from
+  /// JavaScript. Message can have an int32_t, double, bool, or string value
+  /// (objects are not supported).
   virtual void HandleMessage(const Var& message);
 
   /// @}
@@ -269,10 +273,21 @@ class Instance {
 
   /// Binds the given Graphics3D as the current display surface.
   /// See BindGraphics(const Graphics2D& graphics).
+  ///
+  /// @param[in] graphics A <code>Graphics3D_Dev</code> to bind.
+  ///
+  /// @return true if bind was successful or false if the device was not the
+  /// correct type. On success, a reference to the device will be held by the
+  /// instance, so the caller can release its reference if it chooses.
   bool BindGraphics(const Graphics3D_Dev& graphics);
 
   /// Binds the given Surface3D as the current display surface.
   /// See BindGraphics(const Graphics2D& graphics).
+  /// @param[in] graphics A <code>Surface3D_Dev</code> to bind.
+  ///
+  /// @return true if bind was successful or false if the device was not the
+  /// correct type. On success, a reference to the device will be held by the
+  /// instance, so the caller can release its reference if it chooses.
   bool BindGraphics(const Surface3D_Dev& graphics);
 
   /// IsFullFrame() determines if the instance is full-frame (repr).
@@ -354,7 +369,12 @@ class Instance {
   ///       PP_INPUTEVENT_CLASS_WHEEL | PP_INPUTEVENT_CLASS_KEYBOARD);
   ///
   /// @endcode
-  ////
+  ///
+  /// @param event_classes A combination of flags from
+  /// <code>PP_InputEvent_Class</code> that identifies the classes of events
+  /// the instance is requesting. The flags are combined by logically ORing
+  /// their values.
+  ///
   /// @return <code>PP_OK</code> if the operation succeeded,
   /// <code>PP_ERROR_BADARGUMENT</code> if instance is invalid, or
   /// <code>PP_ERROR_NOTSUPPORTED</code> if one of the event class bits were
@@ -378,7 +398,7 @@ class Instance {
   /// one, you'll still receive the next two. You just won't get more events
   /// generated.
   ///
-  /// @param event_classes A combination of flags from
+  /// @param[in] event_classes A combination of flags from
   /// <code>PP_InputEvent_Class</code> that identifies the classes of events the
   /// instance is no longer interested in.
   void ClearInputEventRequest(uint32_t event_classes);
@@ -387,24 +407,6 @@ class Instance {
   /// the DOM element for the given instance. A call to PostMessage() will
   /// not block while the message is processed.
   ///
-  /// @param[in] message A <code>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 instance and the browser.
-  ///
-  /// Listeners for message events in JavaScript code will receive an object
-  /// 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
-  /// <code>http://www.whatwg.org/specs/web-workers/current-work/</code> for
-  /// further information.
-  ///
-  /// @see HandleMessage() for receiving events from JavaScript.
-  ///
   /// <strong>Example:</strong>
   ///
   /// @code
@@ -431,6 +433,23 @@ class Instance {
   /// @endcode
   ///
   /// The browser will pop-up an alert saying "Hello world!"
+  ///
+  /// Listeners for message events in JavaScript code will receive an object
+  /// 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
+  /// <code>http://www.whatwg.org/specs/web-workers/current-work/</code> for
+  /// further information.
+  ///
+  /// Refer to HandleMessage() for receiving events from JavaScript.
+  ///
+  /// @param[in] message A <code>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 instance and the browser.
   void PostMessage(const Var& message);
 
   /// @}
@@ -457,20 +476,32 @@ class Instance {
   /// register with the module (AddPluginInterface) for your interface name to
   /// get the C calls in the first place.
   ///
-  /// @see RemovePerInstanceObject
-  /// @see GetPerInstanceObject
+  /// Refer to RemovePerInstanceObject() and GetPerInstanceObject() for further
+  /// information.
+  ///
+  /// @param[in] interface_name The name of the interface to associate with the
+  /// instance
+  /// @param[in] object
   void AddPerInstanceObject(const std::string& interface_name, void* object);
 
   /// {PENDING: summarize Remove method here}
   ///
-  /// @see AddPerInstanceObject
+  /// Refer to AddPerInstanceObject() for further information.
+  ///
+  /// @param[in] interface_name The name of the interface to associate with the
+  /// instance
+  /// @param[in] object
   void RemovePerInstanceObject(const std::string& interface_name, void* object);
 
   /// Look up an object previously associated with an instance. Returns NULL
   /// if the instance is invalid or there is no object for the given interface
   /// name on the instance.
   ///
-  /// @see AddPerInstanceObject
+  /// Refer to AddPerInstanceObject() for further information.
+  ///
+  /// @param[in] instance
+  /// @param[in] interface_name The name of the interface to associate with the
+  /// instance.
   static void* GetPerInstanceObject(PP_Instance instance,
                                     const std::string& interface_name);
 
diff --git a/ppapi/cpp/paint_manager.h b/ppapi/cpp/paint_manager.h
index 0943c37..e86dc92 100644
--- a/ppapi/cpp/paint_manager.h
+++ b/ppapi/cpp/paint_manager.h
@@ -90,9 +90,11 @@ class PaintManager {
     /// 1/60 second timer to do an invalidate instead. This will limit your
     /// animation to the slower of 60Hz or "however fast Flush can complete."
     ///
-    /// @param graphics A <code>Graphics2D</code> to be painted.
-    /// @param paint_rects A list of rects to paint.
-    /// @param paint_bounds A union of the rects to paint.
+    /// @param[in] graphics A <code>Graphics2D</code> to be painted.
+    /// @param[in] paint_rects A list of rects to paint.
+    /// @param[in] paint_bounds A union of the rects to paint.
+    ///
+    /// @return true if successful, otherwise false.
     virtual bool OnPaint(Graphics2D& graphics,
                          const std::vector<Rect>& paint_rects,
                          const Rect& paint_bounds) = 0;
@@ -155,12 +157,13 @@ class PaintManager {
   /// non-opqaue pixels or aren't sure, set this to false for more general
   /// blending.
   ///
-  /// 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 aren't
-  /// sure, it is always correct to specify that it it not opaque.
+  /// If you set <code>is_always_opaque</code>, your alpha channel should
+  /// always be set to <code>0xFF</code> 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 aren't sure, it is always correct to specify that
+  /// it it not opaque.
   void Initialize(Instance* instance, Client* client, bool is_always_opaque);
 
   /// Setter function setting the max ratio of paint rect area to scroll rect
@@ -223,7 +226,7 @@ class PaintManager {
 
   /// InvalidateRect() Invalidate the provided rect.
   ///
-  /// @param rect The <code>Rect</code> to be invalidated.
+  /// @param[in] rect The <code>Rect</code> to be invalidated.
   void InvalidateRect(const Rect& rect);
 
   /// ScrollRect() scrolls the provided <code>clip_rect</code> by the
@@ -238,7 +241,7 @@ class PaintManager {
   /// (the instance has called SetSize() but we haven't actually painted it
   /// yet), or the current size of no resize is pending.
   ///
-  /// @return The effetive size.
+  /// @return The effective size.
   Size GetEffectiveSize() const;
 
  private:
diff --git a/ppapi/cpp/point.h b/ppapi/cpp/point.h
index 94ad519..9daa6b53d 100644
--- a/ppapi/cpp/point.h
+++ b/ppapi/cpp/point.h
@@ -23,6 +23,7 @@ class Point {
 
   /// A constructor accepting two int32_t values for x and y and converting
   /// them to a Point.
+  ///
   /// @param[in] in_x An int32_t value representing a horizontal coordinate
   /// of a point, starting with 0 as the left-most coordinate.
   /// @param[in] in_y An int32_t value representing a vertical coordinate
@@ -34,6 +35,7 @@ class Point {
 
   /// A constructor accepting a pointer to a PP_Point and converting the
   /// PP_Point to a Point. This is an implicit conversion constructor.
+  ///
   /// @param[in] point A pointer to a PP_Point.
   Point(const PP_Point& point) {  // Implicit.
     point_.x = point.x;
@@ -51,32 +53,38 @@ class Point {
   }
 
   /// Getter function for returning the internal PP_Point struct.
+  ///
   /// @return A const reference to the internal PP_Point struct.
   const PP_Point& pp_point() const {
     return point_;
   }
 
   /// Getter function for returning the internal PP_Point struct.
+  ///
   /// @return A mutable reference to the PP_Point struct.
   PP_Point& pp_point() {
     return point_;
   }
 
   /// Getter function for returning the value of x.
+  ///
   /// @return The value of x for this Point.
   int32_t x() const { return point_.x; }
 
   /// Setter function for setting the value of x.
+  ///
   /// @param[in] in_x A new x value.
   void set_x(int32_t in_x) {
     point_.x = in_x;
   }
 
   /// Getter function for returning the value of y.
+  ///
   /// @return The value of y for this Point.
   int32_t y() const { return point_.y; }
 
   /// Setter function for setting the value of y.
+  ///
   /// @param[in] in_y A new y value.
   void set_y(int32_t in_y) {
     point_.y = in_y;
@@ -84,7 +92,9 @@ class Point {
 
   /// Adds two Points (this and other) together by adding their x values and
   /// y values.
+  ///
   /// @param[in] other A Point.
+  ///
   /// @return A new Point containing the result.
   Point operator+(const Point& other) const {
     return Point(x() + other.x(), y() + other.y());
@@ -92,7 +102,9 @@ class Point {
 
   /// Subtracts one Point from another Point by subtracting their x values
   /// and y values. Returnes a new point with the result.
+  ///
   /// @param[in] other A Point.
+  ///
   /// @return A new Point containing the result.
   Point operator-(const Point& other) const {
     return Point(x() - other.x(), y() - other.y());
@@ -100,7 +112,9 @@ class Point {
 
   /// Adds two Points (this and other) together by adding their x and y
   /// values. Returns this point as the result.
+  ///
   /// @param[in] other A Point.
+  ///
   /// @return This Point containing the result.
   Point& operator+=(const Point& other) {
     point_.x += other.x();
@@ -110,7 +124,9 @@ class Point {
 
   /// Subtracts one Point from another Point by subtracting their x values
   /// and y values. Returns this point as the result.
+  ///
   /// @param[in] other A Point.
+  ///
   /// @return This Point containing the result.
   Point& operator-=(const Point& other) {
     point_.x -= other.x();
@@ -119,6 +135,7 @@ class Point {
   }
 
   /// Swaps the coordinates of two Points.
+  ///
   /// @param[in] other A Point.
   void swap(Point& other) {
     int32_t x = point_.x;
@@ -158,6 +175,7 @@ class FloatPoint {
 
   /// A constructor accepting a pointer to a PP_FloatPoint and converting the
   /// PP_Point to a Point. This is an implicit conversion constructor.
+  ///
   /// @param[in] point A PP_FloatPoint.
   FloatPoint(const PP_FloatPoint& point) {  // Implicit.
     float_point_.x = point.x;
@@ -174,32 +192,38 @@ class FloatPoint {
   }
 
   /// Getter function for returning the internal PP_FloatPoint struct.
+  ///
   /// @return A const reference to the internal PP_FloatPoint struct.
   const PP_FloatPoint& pp_float_point() const {
     return float_point_;
   }
 
   /// Getter function for returning the internal PP_Point struct.
+  ///
   /// @return A mutable reference to the PP_Point struct.
   PP_FloatPoint& pp_float_point() {
     return float_point_;
   }
 
   /// Getter function for returning the value of x.
+  ///
   /// @return The value of x for this Point.
   float x() const { return float_point_.x; }
 
   /// Setter function for setting the value of x.
+  ///
   /// @param[in] in_x A new x value.
   void set_x(float in_x) {
     float_point_.x = in_x;
   }
 
   /// Getter function for returning the value of y.
+  ///
   /// @return The value of y for this Point.
   float y() const { return float_point_.y; }
 
   /// Setter function for setting the value of y.
+  ///
   /// @param[in] in_y A new y value.
   void set_y(float in_y) {
     float_point_.y = in_y;
@@ -207,7 +231,9 @@ class FloatPoint {
 
   /// Adds two Points (this and other) together by adding their x values and
   /// y values.
+  ///
   /// @param[in] other A Point.
+  ///
   /// @return A new Point containing the result.
   FloatPoint operator+(const FloatPoint& other) const {
     return FloatPoint(x() + other.x(), y() + other.y());
@@ -215,7 +241,9 @@ class FloatPoint {
 
   /// Subtracts one Point from another Point by subtracting their x values
   /// and y values. Returnes a new point with the result.
+  ///
   /// @param[in] other A FloatPoint.
+  ///
   /// @return A new Point containing the result.
   FloatPoint operator-(const FloatPoint& other) const {
     return FloatPoint(x() - other.x(), y() - other.y());
@@ -223,7 +251,9 @@ class FloatPoint {
 
   /// Adds two Points (this and other) together by adding their x and y
   /// values. Returns this point as the result.
+  ///
   /// @param[in] other A Point.
+  ///
   /// @return This Point containing the result.
   FloatPoint& operator+=(const FloatPoint& other) {
     float_point_.x += other.x();
@@ -233,7 +263,9 @@ class FloatPoint {
 
   /// Subtracts one Point from another Point by subtracting their x values
   /// and y values. Returns this point as the result.
+  ///
   /// @param[in] other A Point.
+  ///
   /// @return This Point containing the result.
   FloatPoint& operator-=(const FloatPoint& other) {
     float_point_.x -= other.x();
@@ -242,6 +274,7 @@ class FloatPoint {
   }
 
   /// Swaps the coordinates of two Points.
+  ///
   /// @param[in] other A Point.
   void swap(FloatPoint& other) {
     float x = float_point_.x;
@@ -259,16 +292,20 @@ class FloatPoint {
 }  // namespace pp
 
 /// Determines whether the x and y values of two Points are equal.
+///
 /// @param[in] lhs The Point on the left-hand side of the equation.
 /// @param[in] rhs The Point on the right-hand side of the equation.
+///
 /// @return true if they are equal, false if unequal.
 inline bool operator==(const pp::Point& lhs, const pp::Point& rhs) {
   return lhs.x() == rhs.x() && lhs.y() == rhs.y();
 }
 
 /// Determines whether two Points have different coordinates.
+///
 /// @param[in] lhs The Point on the left-hand side of the equation.
 /// @param[in] rhs The Point on the right-hand side of the equation.
+///
 /// @return true if the coordinates of lhs are equal to the coordinates
 /// of rhs, otherwise false.
 inline bool operator!=(const pp::Point& lhs, const pp::Point& rhs) {
@@ -276,16 +313,20 @@ inline bool operator!=(const pp::Point& lhs, const pp::Point& rhs) {
 }
 
 /// Determines whether the x and y values of two FloatPoints are equal.
+///
 /// @param[in] lhs The Point on the left-hand side of the equation.
 /// @param[in] rhs The Point on the right-hand side of the equation.
+///
 /// @return true if they are equal, false if unequal.
 inline bool operator==(const pp::FloatPoint& lhs, const pp::FloatPoint& rhs) {
   return lhs.x() == rhs.x() && lhs.y() == rhs.y();
 }
 
 /// Determines whether two Points have different coordinates.
+///
 /// @param[in] lhs The Point on the left-hand side of the equation.
 /// @param[in] rhs The Point on the right-hand side of the equation.
+///
 /// @return true if the coordinates of lhs are equal to the coordinates
 /// of rhs, otherwise false.
 inline bool operator!=(const pp::FloatPoint& lhs, const pp::FloatPoint& rhs) {
diff --git a/ppapi/cpp/rect.h b/ppapi/cpp/rect.h
index e3243c0..aa659d1 100644
--- a/ppapi/cpp/rect.h
+++ b/ppapi/cpp/rect.h
@@ -299,7 +299,7 @@ class Rect {
   /// IsEmpty() determines if the area of a rectangle is zero. Returns true if
   /// the area of the rectangle is zero.
   ///
-  /// @return True if the area of the rectangle is zero.
+  /// @return true if the area of the rectangle is zero.
   bool IsEmpty() const {
     return rect_.size.width == 0 && rect_.size.height == 0;
   }
@@ -311,7 +311,7 @@ class Rect {
   /// @param[in] point_x An int32_t value representing a x value.
   /// @param[in] point_y An int32_t value representing a y value.
   ///
-  /// @return True if the point_x and point_y fall inside the rectangle.
+  /// @return true if the point_x and point_y fall inside the rectangle.
   bool Contains(int32_t point_x, int32_t point_y) const;
 
   /// Contains() determines if the specified point is contained by this
@@ -319,7 +319,7 @@ class Rect {
   ///
   /// @param[in] point A pointer to a Point representing a 2D coordinate.
   ///
-  /// @return True if the point_x and point_y fall inside the rectangle.
+  /// @return true if the point_x and point_y fall inside the rectangle.
   bool Contains(const Point& point) const {
     return Contains(point.x(), point.y());
   }
@@ -328,7 +328,7 @@ class Rect {
   ///
   /// @param[in] rect A pointer to a <code>Rect</code>.
   ///
-  /// @return True if the rectangle fall inside this rectangle.
+  /// @return true if the rectangle fall inside this rectangle.
   bool Contains(const Rect& rect) const;
 
   /// Insersects() determines if this rectangle intersects the specified
@@ -336,7 +336,7 @@ class Rect {
   ///
   /// @param[in] rect A pointer to a <code>Rect</code>.
   ///
-  /// @return True if the rectangle intersects  this rectangle.
+  /// @return true if the rectangle intersects  this rectangle.
   bool Intersects(const Rect& rect) const;
 
   /// Intersect() computes the intersection of this rectangle with the given
diff --git a/ppapi/cpp/resource.h b/ppapi/cpp/resource.h
index 58e4856..584a82c 100644
--- a/ppapi/cpp/resource.h
+++ b/ppapi/cpp/resource.h
@@ -31,6 +31,7 @@ class Resource {
   /// <code>Resource</code>.
   ///
   /// @param[in] other A Resource.
+  ///
   /// @return A Resource containing the assigned Resource.
   Resource& operator=(const Resource& other);
 
diff --git a/ppapi/cpp/size.h b/ppapi/cpp/size.h
index 9ee09ba..6c93561 100644
--- a/ppapi/cpp/size.h
+++ b/ppapi/cpp/size.h
@@ -110,7 +110,7 @@ class Size {
 
   /// GetArea() determines the area (width * height).
   ///
-  /// @return The area
+  /// @return The area.
   int GetArea() const {
     return width() * height();
   }
diff --git a/ppapi/cpp/url_loader.h b/ppapi/cpp/url_loader.h
index fb22a5d..63bfc00 100644
--- a/ppapi/cpp/url_loader.h
+++ b/ppapi/cpp/url_loader.h
@@ -131,6 +131,7 @@ class URLLoader : public Resource {
   /// 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(const CompletionCallback& cc);
@@ -146,7 +147,8 @@ class URLLoader : public Resource {
   ///
   /// @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 True if the upload progress is available, false if it is not
+  ///
+  /// @return true if the upload progress is available, false if it is not
   /// available.
   bool GetUploadProgress(int64_t* bytes_sent,
                          int64_t* total_bytes_to_be_sent) const;
@@ -164,7 +166,8 @@ class URLLoader : public Resource {
   /// @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 True if the download progress is available, false if it is
+  ///
+  /// @return true if the download progress is available, false if it is
   /// not available.
   bool GetDownloadProgress(int64_t* bytes_received,
                            int64_t* total_bytes_to_be_received) const;
@@ -188,6 +191,7 @@ class URLLoader : public Resource {
   /// 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>.
   int32_t ReadResponseBody(void* buffer,
@@ -204,6 +208,7 @@ class URLLoader : public Resource {
   /// 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>.
   int32_t FinishStreamingToFile(const CompletionCallback& cc);
diff --git a/ppapi/cpp/url_response_info.h b/ppapi/cpp/url_response_info.h
index 71002af..0a56eeb 100644
--- a/ppapi/cpp/url_response_info.h
+++ b/ppapi/cpp/url_response_info.h
@@ -39,6 +39,7 @@ class URLResponseInfo : public Resource {
   ///
   /// @param[in] property A <code>PP_URLResponseProperty</code> identifying the
   /// type of property in the response.
+  ///
   /// @return A <code>Var</code> containing the response property value if
   /// successful, <code>is_undefined Var</code> if an input parameter is
   /// invalid.