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

ppapi/cpp/instance.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_INSTANCE_H_
 #define PPAPI_CPP_INSTANCE_H_
 
 /// @file
 /// Defines the C++ wrapper for an instance.
 
@@ skipping 48 matching lines @@
   /// <strong>Note:</strong> This function may be skipped in certain
   /// call so the instance can perform cleanup-related tasks. Once this function
   /// returns, the <code>PP_Instance</code> handle will be invalid. This means
   /// that you can't do any asynchronous operations such as network requests or
   /// file writes from this destructor since they will be immediately canceled.
   virtual ~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
   /// function will be called immediately after the instance object is
   /// constructed.
   ///
   /// @param[in] argc The number of arguments contained in <code>argn</code>
   /// and <code>argv</code>.
   ///
   /// @param[in] argn An array of argument names.  These argument names are
   /// supplied in the \<embed\> tag, for example:
   /// <code>\<embed id="nacl_module" dimensions="2"\></code> will produce two
   /// argument names: "id" and "dimensions".
   ///
   /// @param[in] argv An array of argument values.  These are the values of the
   /// arguments listed in the \<embed\> tag, for example
   /// <code>\<embed id="nacl_module" dimensions="2"\></code> will produce two
   /// 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[]);
 
   /// @{
   /// @name PPP_Instance methods for the module to override:
 
   /// DidChangeView() is called when the position, the size, or the clip
   /// rectangle of the element in the browser that corresponds to this
   /// instance has changed.
   ///
@@ skipping 70 matching lines @@
   /// you register for the event classes you want by calling
   /// <code>RequestInputEvents</code> or
   /// <code>RequestFilteringInputEvents</code>. If you're still not receiving
   /// keyboard input events, make sure you're returning true (or using a
   /// non-filtered event handler) for mouse events. Otherwise, the instance will
   /// not receive focus and keyboard events will not be sent.
   ///
   /// 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,
   /// the event will be forwarded to the page (and eventually the browser)
   /// for the default handling. For non-filtered events, the return value
   /// will be ignored.
   virtual bool HandleInputEvent(const pp::InputEvent& event);
 
   /// HandleDocumentLoad() is called after Init() for a full-frame
   /// instance that was instantiated based on the MIME type of a DOMWindow
@@ skipping 16 matching lines @@
   ///
   /// @return true if the data was handled, false otherwise.
   virtual bool HandleDocumentLoad(const URLLoader& url_loader);
 
   /// HandleMessage() is a function that the browser calls when PostMessage()
   /// is invoked on the DOM element for the 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] 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
   /// the instance on which it was invoked, with <code>message</code> being a
   /// string <code>Var</code> containing "Hello world!"
   ///
   /// @code
   ///
   /// <body>
   ///   <object id="plugin"
   ///           type="application/x-ppapi-postMessage-example"/>
   ///   <script type="text/javascript">
   ///     document.getElementById('plugin').postMessage("Hello world!");
   ///   </script>
   /// </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);
 
   /// @}
 
   /// @{
   /// @name PPB_Instance methods for querying the browser:
 
   /// BindGraphics() binds the given graphics as the current display surface.
   /// The contents of this device is what will be displayed in the instance's
   /// area on the web page. The device must be a 2D or a 3D device.
@@ skipping 13 matching lines @@
   ///
   /// @param[in] graphics A <code>Graphics2D</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 Graphics2D& graphics);
 
   /// 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).
   /// Such an instance represents the entire document in a frame rather than an
   /// embedded resource. This can happen if the user does a top-level
   /// navigation or the page specifies an iframe to a resource with a MIME
   /// type registered by the module.
   ///
   /// @return true if the instance is full-frame, false if not.
   bool IsFullFrame();
@@ skipping 61 matching lines @@
   ///
   /// <strong>Example:</strong>
   ///
   /// @code
   ///
   ///   RequestInputEvents(PP_INPUTEVENT_CLASS_MOUSE);
   ///   RequestFilteringInputEvents(
   ///       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
   /// illegal. In the case of an invalid bit, all valid bits will be applied
   /// and only the illegal bits will be ignored.
   int32_t RequestFilteringInputEvents(uint32_t event_classes);
 
   /// ClearInputEventRequest() requests that input events corresponding to the
   /// given input classes no longer be delivered to the instance.
   ///
   /// By default, no input events are delivered. If you have previously
   /// requested input events using RequestInputEvents() or
   /// RequestFilteringInputEvents(), this function will unregister handling
   /// for the given instance. This will allow greater browser performance for
   /// those events.
   ///
   /// <strong>Note: </strong> You may still get some input events after
   /// clearing the flag if they were dispatched before the request was cleared.
   /// For example, if there are 3 mouse move events waiting to be delivered,
   /// and you clear the mouse event class during the processing of the first
   /// 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);
 
   /// PostMessage() asynchronously invokes any listeners for message events on
   /// 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
   ///
   /// <body>
   ///   <object id="plugin"
   ///           type="application/x-ppapi-postMessage-example"/>
   ///   <script type="text/javascript">
   ///     var plugin = document.getElementById('plugin');
   ///     plugin.AddEventListener("message",
   ///                             function(message) { alert(message.data); },
   ///                             false);
   ///   </script>
   /// </body>
   ///
   /// @endcode
   ///
   /// The instance then invokes PostMessage() as follows:
   ///
   /// @code
   ///
   ///  PostMessage(pp::Var("Hello world!"));
   ///
   /// @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);
 
   /// @}
 
   /// AddPerInstanceObject() associates an instance with an interface,
   /// creating an object... {PENDING: clarify!}
   ///
   /// Many optional interfaces are associated with a plugin instance. For
   /// example, the find in PPP_Find interface receives updates on a per-instance
   /// basis. This "per-instance" tracking allows such objects to associate
   /// themselves with an instance as "the" handler for that interface name.
   ///
   /// In the case of the find example, the find object registers with its
   /// associated instance in its constructor and unregisters in its destructor.
   /// Then whenever it gets updates with a PP_Instance parameter, it can
   /// map back to the find object corresponding to that given PP_Instance by
   /// calling GetPerInstanceObject.
   ///
   /// This lookup is done on a per-interface-name basis. This means you can
   /// only have one object of a given interface name associated with an
   /// instance.
   ///
   /// If you are adding a handler for an additional interface, be sure to
   /// 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);
 
  private:
   PP_Instance pp_instance_;
 
   typedef std::map<std::string, void*> InterfaceNameToObjectMap;
   InterfaceNameToObjectMap interface_name_to_objects_;
 };
 
 }  // namespace pp
 
 #endif  // PPAPI_CPP_INSTANCE_H_