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

ppapi/cpp/input_event.h

 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef PPAPI_CPP_INPUT_EVENT_H_
 #define PPAPI_CPP_INPUT_EVENT_H_
 
 #include <string>
 
 #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;
 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 {
 ///       pp::MouseInputEvent mouse_event(event);
 ///       return HandleMouseDown(mouse_event.GetMousePosition());
 ///     }
 ///     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,
                   uint32_t modifiers,
                   PP_InputEvent_MouseButton mouse_button,
                   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
   /// mouse drags. The return value will be (0, 0) for non-mouse events.
   Point GetPosition() const;
 
   // TODO(brettw) figure out exactly what this means.
   int32_t GetClickCount() const;
 };
 
 class WheelInputEvent : public InputEvent {
  public:
   /// 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 modifiers A bit field combination of the

[dmichael (off chromium), 2011/08/12 21:32:37]

[in]?

[jond, 2011/08/15 17:32:11]

Done.

+  /// <code>PP_InputEvent_Modifier</code> flags.
+  ///
+  /// @param[in] wheel_delta The scroll wheel's horizontal and vertical scroll
+  /// amounts.
+  ///
+  /// @param[in] wheel_ticks he 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

[dmichael (off chromium), 2011/08/12 21:32:37]

What's the asterisk mean here? Is that intentional?

[jond, 2011/08/15 17:32:11]

Done.

+  /// by pages. When false, the user user is requesting to scroll by lines.

[dmichael (off chromium), 2011/08/12 21:32:37]

you have an extra 'user'

[jond, 2011/08/15 17:32:11]

Done.

   WheelInputEvent(Instance* instance,
                   PP_TimeTicks time_stamp,
                   uint32_t modifiers,
                   const FloatPoint& wheel_delta,
                   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
   /// based on the speed of the scrolling.
   ///
   /// Devices will be of varying resolution. Some mice with large detents will
   /// 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.
+  // @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;
 };
 
 class KeyboardInputEvent : public InputEvent {
  public:
   /// 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
+  /// single null-terminated UTF-8 character. Any unused bytes will be filled
+  /// with null bytes. Since the maximum UTF-8 character is 4 bytes, there will
+  /// always be at least one null at the end so you can treat this as a
+  /// null-termianted UTF-8 string.

[dmichael (off chromium), 2011/08/12 21:32:37]

Oops, everything after the first sentence is wrong now in the new API. Please
delete all but the first sentence. In fact...  the first sentence should
probably be tweaked a little:
'This value represents the typed character as a UTF-8 string.'

[jond, 2011/08/15 17:32:11]

Done.

   KeyboardInputEvent(Instance* instance,
                      PP_InputEvent_Type type,
                      PP_TimeTicks time_stamp,
                      uint32_t modifiers,
                      uint32_t key_code,
                      const Var& character_text);
 
   /// 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;
 
   /// Returns the typed character for the given character event.
   ///
   /// @return A string var representing a single typed character for character
   /// input events. For non-character input events the return value will be an
   /// undefined var.
   Var GetCharacterText() const;
 };
 
 }  // namespace pp
 
 #endif  // PPAPI_CPP_INPUT_EVENT_H_