Fixed misspelled word in ppb_image_data. Updated/rewrote docs in the other three files.

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

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

8 files changed, 150 insertions, 80 deletions

diff --git a/ppapi/api/ppb_fullscreen.idl b/ppapi/api/ppb_fullscreen.idl
index cb3a4a2..7ac3daa 100644
--- a/ppapi/api/ppb_fullscreen.idl
+++ b/ppapi/api/ppb_fullscreen.idl
@@ -5,40 +5,69 @@
 
 
 /**
- * This file defines the <code>PPB_Fullscreen</code> interface.
+ * This file defines the <code>PPB_Fullscreen</code> interface for
+ * handling transitions of a module instance to and from fullscreen mode.
  */
 
 label Chrome {
   M16 = 1.0
 };
 
+/** 
+ * The <code>PPB_Fullscreen</code> interface is implemented by the browser.
+ * This interface provides a way of checking the current screen mode and
+ * toggling fullscreen mode.
+ */
 interface PPB_Fullscreen {
   /**
-   * Checks whether the plugin instance is currently in fullscreen mode.
+   * IsFullscreen() checks whether the module instance is currently in
+   * fullscreen mode.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance
+   * of a module.
+   *
+   * @return <code>PP_TRUE</code> if the module instance is in fullscreen mode,
+   * <code>PP_FALSE</code> if the module instance is not in fullscreen mode.
    */
   PP_Bool IsFullscreen(
       [in] PP_Instance instance);
 
   /**
-   * Switches the plugin instance to/from fullscreen mode. Returns PP_TRUE on
-   * success, PP_FALSE on failure.
+   * SetFullscreen() switches the module instance to and from fullscreen
+   * mode. 
    *
-   * The transition to and from fullscreen is asynchronous.
-   * During the transition, IsFullscreen will return the original value, and
-   * no 2D or 3D device can be bound. The transition ends at DidChangeView
-   * when IsFullscreen returns the new value. You might receive other
-   * DidChangeView calls while in transition.
+   * The transition to and from fullscreen mode is asynchronous. During the
+   * transition, IsFullscreen() will return the previous value and
+   * no 2D or 3D device can be bound. The transition ends at DidChangeView()
+   * when IsFullscreen() returns the new value. You might receive other
+   * DidChangeView() calls while in transition.
    *
-   * The transition to fullscreen can only occur while the browser is
-   * processing a user gesture, even if PP_TRUE is returned.
+   * The transition to fullscreen mode can only occur while the browser is
+   * processing a user gesture, even if <code>PP_TRUE</code> is returned.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance
+   * of a module.
+   * @param[in] fullscreen <code>PP_TRUE</code> to enter fullscreen mode, or
+   * <code>PP_FALSE</code> to exit fullscreen mode.
+   * 
+   * @return <code>PP_TRUE</code> on success or <code>PP_FALSE</code> on
+   * failure.
    */
   PP_Bool SetFullscreen(
       [in] PP_Instance instance,
       [in] PP_Bool fullscreen);
 
   /**
-   * Gets the size of the screen in pixels. When going fullscreen, the instance
-   * will be resized to that size.
+   * GetScreenSize() gets the size of the screen in pixels. The module instance
+   * will be resized to this size when SetFullscreen() is called to enter
+   * fullscreen mode.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance
+   * of a module.
+   * @param[out] size The size of the entire screen in pixels.
+   *
+   * @return <code>PP_TRUE</code> on success or <code>PP_FALSE</code> on
+   * failure.
    */
   PP_Bool GetScreenSize(
       [in] PP_Instance instance,
diff --git a/ppapi/api/ppb_image_data.idl b/ppapi/api/ppb_image_data.idl
index fd05dee..790be4e 100644
--- a/ppapi/api/ppb_image_data.idl
+++ b/ppapi/api/ppb_image_data.idl
@@ -128,13 +128,13 @@ interface PPB_ImageData {
       [in] PP_Bool init_to_zero);
 
   /**
-   * IsImageData() determiens if a given resource is image data.
+   * IsImageData() determines if a given resource is image data.
    *
    * @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
+   * resource is an image data or <code>PP_FALSE</code> if the resource is
    * invalid or some type other than image data.
    */
   PP_Bool IsImageData(
diff --git a/ppapi/api/ppb_mouse_lock.idl b/ppapi/api/ppb_mouse_lock.idl
index 8c5a96f..52fb581 100644
--- a/ppapi/api/ppb_mouse_lock.idl
+++ b/ppapi/api/ppb_mouse_lock.idl
@@ -4,7 +4,8 @@
  */
 
 /**
- * This file defines the <code>PPB_MouseLock</code> interface.
+ * This file defines the <code>PPB_MouseLock</code> interface for
+ * locking the target of mouse events to a specific module instance.
  */
 
 label Chrome {
@@ -13,27 +14,29 @@ label Chrome {
 
 /**
  * The <code>PPB_MouseLock</code> interface is implemented by the browser.
- * It provides a way of locking the target of mouse events to a single plugin
- * instance and removing the cursor from view. This is a useful input mode for
- * certain classes of applications, especially first person perspective 3D
- * applications and 3D modelling software.
+ * This interface provides a way of locking the target of mouse events to a
+ * single module instance and removing the cursor from view. This mode is
+ * useful for certain classes of applications, especially first-person
+ * perspective 3D applications and 3D modeling software.
  */
 interface PPB_MouseLock {
   /**
-   * Requests the mouse to be locked. The browser will permit mouse lock only
-   * while the tab is in fullscreen mode.
+   * LockMouse() requests the mouse to be locked. The browser will permit mouse 
+   * lock only while the tab is in fullscreen mode.
    *
    * While the mouse is locked, the cursor is implicitly hidden from the user.
    * Any movement of the mouse will generate a
-   * <code>PP_INPUTEVENT_TYPE_MOUSEMOVE</code>. The <code>GetPosition</code> of
-   * <code>PPB_MouseInputEvent</code> reports the last known mouse position just
-   * as mouse lock was entered; while the <code>GetMovement</code> provides
-   * relative movement information, which indicates what the change in position
-   * of the mouse would be had it not been locked.
+   * <code>PP_INPUTEVENT_TYPE_MOUSEMOVE</code> event. The    
+   * <code>GetPosition()</code> function in the <code>PPB_MouseInputEvent</code>
+   * interface reports the last known mouse position just as mouse lock was
+   * entered. The <code>GetMovement()</code> function provides relative movement
+   * information indicating what the change in position of the mouse would be
+   * had it not been locked.
    *
-   * The browser may revoke mouse lock for reasons including but not limited to
-   * the user pressing the ESC key, the user activating another program via a
-   * reserved keystroke (e.g., ALT+TAB), or some other system event.
+   * The browser may revoke the mouse lock for reasons including (but not
+   * limited to) the user pressing the ESC key, the user activating another
+   * program using a reserved keystroke (e.g. ALT+TAB), or some other system
+   * event.
    *
    * @param[in] instance A <code>PP_Instance</code> identifying one instance
    * of a module.
@@ -46,9 +49,10 @@ interface PPB_MouseLock {
                     [in] PP_CompletionCallback callback);
 
   /**
-   * Causes the mouse to be unlocked, allowing it to track user movement again.
-   * This is an asynchronous operation. The plugin instance will be notified via
-   * the <code>PPP_MouseLock</code> interface when it has lost the mouse lock.
+   * UnlockMouse() causes the mouse to be unlocked, allowing it to track user
+   * movement again. This is an asynchronous operation. The module instance
+   * will be notified using the <code>PPP_MouseLock</code> interface when it
+   * has lost the mouse lock.
    *
    * @param[in] instance A <code>PP_Instance</code> identifying one instance
    * of a module.
diff --git a/ppapi/api/ppp_mouse_lock.idl b/ppapi/api/ppp_mouse_lock.idl
index 07f0ea6..21d03f5 100644
--- a/ppapi/api/ppp_mouse_lock.idl
+++ b/ppapi/api/ppp_mouse_lock.idl
@@ -4,7 +4,9 @@
  */
 
 /**
- * This file defines the <code>PPP_MouseLock</code> interface.
+ * This file defines the <code>PPP_MouseLock</code> interface containing a 
+ * function that you must implement to receive mouse lock events from the
+ * browser. 
  */
 
 label Chrome {
@@ -12,13 +14,13 @@ label Chrome {
 };
 
 /**
- * The <code>PPP_MouseLock</code> interface contains pointers to functions
- * that you must implement to receive mouse lock events from the browser.
+ * The <code>PPP_MouseLock</code> interface contains a function that you must
+ * implement to receive mouse lock events from the browser.
  */
 interface PPP_MouseLock {
   /**
-   * Called when the instance loses the mouse lock, e.g. because the user
-   * pressed the ESC key.
+   * MouseLockLost() is called when the instance loses the mouse lock, such as   
+   * when the user presses the ESC key.
    *
    * @param[in] instance A <code>PP_Instance</code> identifying one instance
    * of a module.
diff --git a/ppapi/c/ppb_fullscreen.h b/ppapi/c/ppb_fullscreen.h
index 18d52ba..72ff98d 100644
--- a/ppapi/c/ppb_fullscreen.h
+++ b/ppapi/c/ppb_fullscreen.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From ppb_fullscreen.idl modified Sun Oct 16 22:32:54 2011. */
+/* From ppb_fullscreen.idl modified Wed Dec 21 11:00:23 2011. */
 
 #ifndef PPAPI_C_PPB_FULLSCREEN_H_
 #define PPAPI_C_PPB_FULLSCREEN_H_
@@ -19,7 +19,8 @@
 
 /**
  * @file
- * This file defines the <code>PPB_Fullscreen</code> interface.
+ * This file defines the <code>PPB_Fullscreen</code> interface for
+ * handling transitions of a module instance to and from fullscreen mode.
  */
 
 
@@ -27,28 +28,56 @@
  * @addtogroup Interfaces
  * @{
  */
+/**
+ * The <code>PPB_Fullscreen</code> interface is implemented by the browser.
+ * This interface provides a way of checking the current screen mode and
+ * toggling fullscreen mode.
+ */
 struct PPB_Fullscreen {
   /**
-   * Checks whether the plugin instance is currently in fullscreen mode.
+   * IsFullscreen() checks whether the module instance is currently in
+   * fullscreen mode.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance
+   * of a module.
+   *
+   * @return <code>PP_TRUE</code> if the module instance is in fullscreen mode,
+   * <code>PP_FALSE</code> if the module instance is not in fullscreen mode.
    */
   PP_Bool (*IsFullscreen)(PP_Instance instance);
   /**
-   * Switches the plugin instance to/from fullscreen mode. Returns PP_TRUE on
-   * success, PP_FALSE on failure.
+   * SetFullscreen() switches the module instance to and from fullscreen
+   * mode.
    *
-   * The transition to and from fullscreen is asynchronous.
-   * During the transition, IsFullscreen will return the original value, and
-   * no 2D or 3D device can be bound. The transition ends at DidChangeView
-   * when IsFullscreen returns the new value. You might receive other
-   * DidChangeView calls while in transition.
+   * The transition to and from fullscreen mode is asynchronous. During the
+   * transition, IsFullscreen() will return the previous value and
+   * no 2D or 3D device can be bound. The transition ends at DidChangeView()
+   * when IsFullscreen() returns the new value. You might receive other
+   * DidChangeView() calls while in transition.
    *
-   * The transition to fullscreen can only occur while the browser is
-   * processing a user gesture, even if PP_TRUE is returned.
+   * The transition to fullscreen mode can only occur while the browser is
+   * processing a user gesture, even if <code>PP_TRUE</code> is returned.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance
+   * of a module.
+   * @param[in] fullscreen <code>PP_TRUE</code> to enter fullscreen mode, or
+   * <code>PP_FALSE</code> to exit fullscreen mode.
+   *
+   * @return <code>PP_TRUE</code> on success or <code>PP_FALSE</code> on
+   * failure.
    */
   PP_Bool (*SetFullscreen)(PP_Instance instance, PP_Bool fullscreen);
   /**
-   * Gets the size of the screen in pixels. When going fullscreen, the instance
-   * will be resized to that size.
+   * GetScreenSize() gets the size of the screen in pixels. The module instance
+   * will be resized to this size when SetFullscreen() is called to enter
+   * fullscreen mode.
+   *
+   * @param[in] instance A <code>PP_Instance</code> identifying one instance
+   * of a module.
+   * @param[out] size The size of the entire screen in pixels.
+   *
+   * @return <code>PP_TRUE</code> on success or <code>PP_FALSE</code> on
+   * failure.
    */
   PP_Bool (*GetScreenSize)(PP_Instance instance, struct PP_Size* size);
 };
diff --git a/ppapi/c/ppb_image_data.h b/ppapi/c/ppb_image_data.h
index e8b42c4..982e29d 100644
--- a/ppapi/c/ppb_image_data.h
+++ b/ppapi/c/ppb_image_data.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From ppb_image_data.idl modified Mon Aug 29 10:11:34 2011. */
+/* From ppb_image_data.idl modified Tue Nov  8 15:46:54 2011. */
 
 #ifndef PPAPI_C_PPB_IMAGE_DATA_H_
 #define PPAPI_C_PPB_IMAGE_DATA_H_
@@ -152,13 +152,13 @@ struct PPB_ImageData {
                         const struct PP_Size* size,
                         PP_Bool init_to_zero);
   /**
-   * IsImageData() determiens if a given resource is image data.
+   * IsImageData() determines if a given resource is image data.
    *
    * @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
+   * resource is an image data or <code>PP_FALSE</code> if the resource is
    * invalid or some type other than image data.
    */
   PP_Bool (*IsImageData)(PP_Resource image_data);
diff --git a/ppapi/c/ppb_mouse_lock.h b/ppapi/c/ppb_mouse_lock.h
index c7b074d..b04e7a0 100644
--- a/ppapi/c/ppb_mouse_lock.h
+++ b/ppapi/c/ppb_mouse_lock.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From ppb_mouse_lock.idl modified Fri Oct 14 18:59:25 2011. */
+/* From ppb_mouse_lock.idl modified Mon Nov 28 10:59:14 2011. */
 
 #ifndef PPAPI_C_PPB_MOUSE_LOCK_H_
 #define PPAPI_C_PPB_MOUSE_LOCK_H_
@@ -18,7 +18,8 @@
 
 /**
  * @file
- * This file defines the <code>PPB_MouseLock</code> interface.
+ * This file defines the <code>PPB_MouseLock</code> interface for
+ * locking the target of mouse events to a specific module instance.
  */
 
 
@@ -28,27 +29,29 @@
  */
 /**
  * The <code>PPB_MouseLock</code> interface is implemented by the browser.
- * It provides a way of locking the target of mouse events to a single plugin
- * instance and removing the cursor from view. This is a useful input mode for
- * certain classes of applications, especially first person perspective 3D
- * applications and 3D modelling software.
+ * This interface provides a way of locking the target of mouse events to a
+ * single module instance and removing the cursor from view. This mode is
+ * useful for certain classes of applications, especially first-person
+ * perspective 3D applications and 3D modeling software.
  */
 struct PPB_MouseLock {
   /**
-   * Requests the mouse to be locked. The browser will permit mouse lock only
-   * while the tab is in fullscreen mode.
+   * LockMouse() requests the mouse to be locked. The browser will permit mouse
+   * lock only while the tab is in fullscreen mode.
    *
    * While the mouse is locked, the cursor is implicitly hidden from the user.
    * Any movement of the mouse will generate a
-   * <code>PP_INPUTEVENT_TYPE_MOUSEMOVE</code>. The <code>GetPosition</code> of
-   * <code>PPB_MouseInputEvent</code> reports the last known mouse position just
-   * as mouse lock was entered; while the <code>GetMovement</code> provides
-   * relative movement information, which indicates what the change in position
-   * of the mouse would be had it not been locked.
+   * <code>PP_INPUTEVENT_TYPE_MOUSEMOVE</code> event. The
+   * <code>GetPosition()</code> function in the <code>PPB_MouseInputEvent</code>
+   * interface reports the last known mouse position just as mouse lock was
+   * entered. The <code>GetMovement()</code> function provides relative movement
+   * information indicating what the change in position of the mouse would be
+   * had it not been locked.
    *
-   * The browser may revoke mouse lock for reasons including but not limited to
-   * the user pressing the ESC key, the user activating another program via a
-   * reserved keystroke (e.g., ALT+TAB), or some other system event.
+   * The browser may revoke the mouse lock for reasons including (but not
+   * limited to) the user pressing the ESC key, the user activating another
+   * program using a reserved keystroke (e.g. ALT+TAB), or some other system
+   * event.
    *
    * @param[in] instance A <code>PP_Instance</code> identifying one instance
    * of a module.
@@ -60,9 +63,10 @@ struct PPB_MouseLock {
   int32_t (*LockMouse)(PP_Instance instance,
                        struct PP_CompletionCallback callback);
   /**
-   * Causes the mouse to be unlocked, allowing it to track user movement again.
-   * This is an asynchronous operation. The plugin instance will be notified via
-   * the <code>PPP_MouseLock</code> interface when it has lost the mouse lock.
+   * UnlockMouse() causes the mouse to be unlocked, allowing it to track user
+   * movement again. This is an asynchronous operation. The module instance
+   * will be notified using the <code>PPP_MouseLock</code> interface when it
+   * has lost the mouse lock.
    *
    * @param[in] instance A <code>PP_Instance</code> identifying one instance
    * of a module.
diff --git a/ppapi/c/ppp_mouse_lock.h b/ppapi/c/ppp_mouse_lock.h
index 850813a..376835a 100644
--- a/ppapi/c/ppp_mouse_lock.h
+++ b/ppapi/c/ppp_mouse_lock.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From ppp_mouse_lock.idl modified Fri Oct 14 19:00:26 2011. */
+/* From ppp_mouse_lock.idl modified Wed Nov  9 12:07:33 2011. */
 
 #ifndef PPAPI_C_PPP_MOUSE_LOCK_H_
 #define PPAPI_C_PPP_MOUSE_LOCK_H_
@@ -17,7 +17,9 @@
 
 /**
  * @file
- * This file defines the <code>PPP_MouseLock</code> interface.
+ * This file defines the <code>PPP_MouseLock</code> interface containing a
+ * function that you must implement to receive mouse lock events from the
+ * browser.
  */
 
 
@@ -26,13 +28,13 @@
  * @{
  */
 /**
- * The <code>PPP_MouseLock</code> interface contains pointers to functions
- * that you must implement to receive mouse lock events from the browser.
+ * The <code>PPP_MouseLock</code> interface contains a function that you must
+ * implement to receive mouse lock events from the browser.
  */
 struct PPP_MouseLock {
   /**
-   * Called when the instance loses the mouse lock, e.g. because the user
-   * pressed the ESC key.
+   * MouseLockLost() is called when the instance loses the mouse lock, such as
+   * when the user presses the ESC key.
    *
    * @param[in] instance A <code>PP_Instance</code> identifying one instance
    * of a module.