Updated grammar, added resource argument to all functions.

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

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

2 files changed, 163 insertions, 113 deletions

diff --git a/ppapi/api/ppb_view.idl b/ppapi/api/ppb_view.idl
index acb7958..b51756c 100644
--- a/ppapi/api/ppb_view.idl
+++ b/ppapi/api/ppb_view.idl
@@ -4,8 +4,8 @@
  */
 
 /**
- * Defines the <code>PPB_View</code> struct representing the state of the
- * view of an instance.
+ * This file defines the <code>PPB_View</code> struct representing the state
+ * of the view of an instance.
  */
 
 label Chrome {
@@ -14,17 +14,20 @@ label Chrome {
 
 /**
  * <code>PPB_View</code> represents the state of the view of an instance.
- * You will receive new view information via
+ * You will receive new view information using
  * <code>PPP_Instance.DidChangeView</code>.
  */
 [macro="PPB_VIEW_INTERFACE"]
 interface PPB_View {
   /**
-   * <code>IsView()</code> determines if the given resource is a valid
+   * IsView() determines if the given resource is a valid
    * <code>PPB_View</code> resource. Note that <code>PPB_ViewChanged</code>
    * resources derive from <code>PPB_View</code> and will return true here
    * as well.
    *
+   * @param resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_View</code> resource.
+   *
    * @return <code>PP_TRUE</code> if the given resource supports
    * <code>PPB_View</code> or <code>PP_FALSE</code> if it is an invalid
    * resource or is a resource of another type.
@@ -32,60 +35,77 @@ interface PPB_View {
   PP_Bool IsView([in] PP_Resource resource);
 
   /**
-   * <code>GetRect()</code> retrieves the rectangle of the instance
-   * associated with the view changed notification relative to the upper left
-   * of the browser viewport. This position changes when the page is scrolled.
+   * GetRect() retrieves the rectangle of the module instance associated
+   * with a view changed notification relative to the upper-left of the browser
+   * viewport. This position changes when the page is scrolled.
    *
    * The returned rectangle may not be inside the visible portion of the
-   * viewport if the instance is scrolled off the page. Therefore, the position
-   * may be negative or larger than the size of the page. The size will always
-   * reflect the size of the plugin were it to be scrolled entirely into view.
+   * viewport if the module instance is scrolled off the page. Therefore, the
+   * position may be negative or larger than the size of the page. The size will
+   * always reflect the size of the module were it to be scrolled entirely into
+   * view.
+   *
+   * In general, most modules will not need to worry about the position of the
+   * module instance in the viewport, and only need to use the size.
    *
-   * In general, most plugins will not need to worry about the position of the
-   * instance in the viewport, and only need to use the size.
+   * @param resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_View</code> resource.
    *
-   * @param rect Output argument receiving the rectangle on success.
+   * @param rect A <code>PP_Rect</code> receiving the rectangle on success.
    *
    * @return Returns <code>PP_TRUE</code> if the resource was valid and the
-   * viewport rect was filled in, <code>PP_FALSE</code> if not.
+   * viewport rectangle was filled in, <code>PP_FALSE</code> if not.
    */
   PP_Bool GetRect([in] PP_Resource resource,
                   [out] PP_Rect rect);
 
   /**
-   * <code>IsFullscreen()</code> returns whether the instance is currently
+   * IsFullscreen() returns whether the instance is currently
    * displaying in fullscreen mode.
    *
+   * @param resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_View</code> resource.
+   *
    * @return <code>PP_TRUE</code> if the instance is in full screen mode,
    * or <code>PP_FALSE</code> if it's not or the resource is invalid.
    */
   PP_Bool IsFullscreen([in] PP_Resource resource);
 
   /**
-   * <code>IsVisible()</code> returns whether the instance is plausibly
-   * visible to the user. You should use this flag to throttle or stop updates
-   * for invisible plugins.
+   * IsVisible() determines whether the module instance might be visible to
+   * the user. For example, the Chrome window could be minimized or another
+   * window could be over it. In both of these cases, the module instance
+   * would not be visible to the user, but IsVisible() will return true.
    *
-   * Thie measure incorporates both whether the instance is scrolled into
-   * view (whether the clip rect is nonempty) and whether the page is plausibly
-   * visible to the user (<code>IsPageVisible()</code>).
+   * Use the result to speed up or stop updates for invisible module
+   * instances.
    *
-   * @return <code>PP_TRUE</code> if the instance is plausibly visible to the
+   * This function performs the duties of GetRect() (determining whether the
+   * module instance is scrolled into view and the clip rectangle is nonempty)
+   * and IsPageVisible() (whether the page is visible to the user).
+   *
+   * @param resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_View</code> resource. 
+   *
+   * @return <code>PP_TRUE</code> if the instance might be visible to the
    * user, <code>PP_FALSE</code> if it is definitely not visible.
    */
   PP_Bool IsVisible([in] PP_Resource resource);
 
   /**
-   * <code>IsPageVisible()</code> determines if the page that contains the
-   * instance is visible. The most common cause of invisible pages is that
+   * IsPageVisible() determines if the page that contains the module instance
+   * is visible. The most common cause of invisible pages is that
    * the page is in a background tab in the browser.
    *
-   * Most applications should use <code>IsVisible()</code> rather than
-   * this function since the instance could be scrolled off of a visible
-   * page, and this function will still return true. However, depending on
-   * how your plugin interacts with the page, there may be certain updates
-   * that you may want to perform when the page is visible even if your
-   * specific instance isn't.
+   * Most applications should use IsVisible() instead of this function since
+   * the module instance could be scrolled off of a visible page, and this
+   * function will still return true. However, depending on how your module
+   * interacts with the page, there may be certain updates that you may want to
+   * perform when the page is visible even if your specific module instance is
+   * not visible.
+   *
+   * @param resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_View</code> resource. 
    *
    * @return <code>PP_TRUE</code> if the instance is plausibly visible to the
    * user, <code>PP_FALSE</code> if it is definitely not visible.
@@ -93,37 +113,42 @@ interface PPB_View {
   PP_Bool IsPageVisible([in] PP_Resource resource);
 
   /**
-   * <code>GetClipRect()</code> returns the clip rectangle relative to the
-   * upper left corner of the instance. This rectangle indicates which parts of
-   * the instance are scrolled into view.
-   *
-   * If the instance is scrolled off the view, the return value will be
-   * (0, 0, 0, 0). This clip rect does <i>not</i> take into account page
-   * visibility. This means if the instance is scrolled into view but the page
-   * itself is in an invisible tab, the return rect will contain the visible
-   * rect assuming the page was visible. See <code>IsPageVisible()</code> and
-   * <code>IsVisible()</code> if you want to handle this case.
-   *
-   * Most applications will not need to worry about the clip. The recommended
-   * behavior is to do full updates if the instance is visible as determined by
-   * <code>IsVisible()</code> and do no updates if not.
+   * GetClipRect() returns the clip rectangle relative to the upper-left corner
+   * of the module instance. This rectangle indicates the portions of the module
+   * instance that are scrolled into view.
+   *
+   * If the module instance is scrolled off the view, the return value will be
+   * (0, 0, 0, 0). This clip rectangle does <i>not</i> take into account page
+   * visibility. Therefore, if the module instance is scrolled into view, but
+   * the page itself is on a tab that is not visible, the return rectangle will
+   * contain the visible rectangle as though the page were visible. Refer to
+   * IsPageVisible() and IsVisible() if you want to account for page
+   * visibility.
+   *
+   * Most applications will not need to worry about the clip rectangle. The
+   * recommended behavior is to do full updates if the module instance is
+   * visible, as determined by IsVisible(), and do no updates if it is not
+   * visible.
    *
    * However, if the cost for computing pixels is very high for your
-   * application or the pages you're targeting frequently have very large
-   * instances with small visible portions, you may wish to optimize further.
-   * In this case, the clip rect will tell you which parts of the plugin to
-   * update.
+   * application, or the pages you're targeting frequently have very large
+   * module instances with small visible portions, you may wish to optimize
+   * further. In this case, the clip rectangle will tell you which parts of
+   * the module to update.
    *
    * Note that painting of the page and sending of view changed updates
    * happens asynchronously. This means when the user scrolls, for example,
-   * it is likely that the previous backing store of the instance will be used
-   * for the first paint, and will be updated later when your application
-   * generates new content with the new clip. This may cause flickering at the
-   * boundaries when scrolling. If you do choose to do partial updates, you may
-   * want to think about what color the invisible portions of your backing
-   * store contain (be it transparent or some background color) or to paint
-   * a certain region outside the clip to reduce the visual distraction when
-   * this happens.
+   * it is likely that the previous backing store of the module instance will
+   * be used for the first paint, and will be updated later when your
+   * application generates new content with the new clip. This may cause
+   * flickering at the boundaries when scrolling. If you do choose to do
+   * partial updates, you may want to think about what color the invisible
+   * portions of your backing store contain (be it transparent or some
+   * background color) or to paint a certain region outside the clip to reduce
+   * the visual distraction when this happens.
+   *
+   * @param resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_View</code> resource. 
    *
    * @param clip Output argument receiving the clip rect on success.
    *
diff --git a/ppapi/c/ppb_view.h b/ppapi/c/ppb_view.h
index 513b558..a2a92ac 100644
--- a/ppapi/c/ppb_view.h
+++ b/ppapi/c/ppb_view.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From ppb_view.idl modified Mon Feb  6 14:05:16 2012. */
+/* From ppb_view.idl modified Fri Feb 17 09:09:15 2012. */
 
 #ifndef PPAPI_C_PPB_VIEW_H_
 #define PPAPI_C_PPB_VIEW_H_
@@ -21,8 +21,8 @@
 
 /**
  * @file
- * Defines the <code>PPB_View</code> struct representing the state of the
- * view of an instance.
+ * This file defines the <code>PPB_View</code> struct representing the state
+ * of the view of an instance.
  */
 
 
@@ -32,109 +32,134 @@
  */
 /**
  * <code>PPB_View</code> represents the state of the view of an instance.
- * You will receive new view information via
+ * You will receive new view information using
  * <code>PPP_Instance.DidChangeView</code>.
  */
 struct PPB_View_1_0 {
   /**
-   * <code>IsView()</code> determines if the given resource is a valid
+   * IsView() determines if the given resource is a valid
    * <code>PPB_View</code> resource. Note that <code>PPB_ViewChanged</code>
    * resources derive from <code>PPB_View</code> and will return true here
    * as well.
    *
+   * @param resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_View</code> resource.
+   *
    * @return <code>PP_TRUE</code> if the given resource supports
    * <code>PPB_View</code> or <code>PP_FALSE</code> if it is an invalid
    * resource or is a resource of another type.
    */
   PP_Bool (*IsView)(PP_Resource resource);
   /**
-   * <code>GetRect()</code> retrieves the rectangle of the instance
-   * associated with the view changed notification relative to the upper left
-   * of the browser viewport. This position changes when the page is scrolled.
+   * GetRect() retrieves the rectangle of the module instance associated
+   * with a view changed notification relative to the upper-left of the browser
+   * viewport. This position changes when the page is scrolled.
    *
    * The returned rectangle may not be inside the visible portion of the
-   * viewport if the instance is scrolled off the page. Therefore, the position
-   * may be negative or larger than the size of the page. The size will always
-   * reflect the size of the plugin were it to be scrolled entirely into view.
+   * viewport if the module instance is scrolled off the page. Therefore, the
+   * position may be negative or larger than the size of the page. The size will
+   * always reflect the size of the module were it to be scrolled entirely into
+   * view.
+   *
+   * In general, most modules will not need to worry about the position of the
+   * module instance in the viewport, and only need to use the size.
    *
-   * In general, most plugins will not need to worry about the position of the
-   * instance in the viewport, and only need to use the size.
+   * @param resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_View</code> resource.
    *
-   * @param rect Output argument receiving the rectangle on success.
+   * @param rect A <code>PP_Rect</code> receiving the rectangle on success.
    *
    * @return Returns <code>PP_TRUE</code> if the resource was valid and the
-   * viewport rect was filled in, <code>PP_FALSE</code> if not.
+   * viewport rectangle was filled in, <code>PP_FALSE</code> if not.
    */
   PP_Bool (*GetRect)(PP_Resource resource, struct PP_Rect* rect);
   /**
-   * <code>IsFullscreen()</code> returns whether the instance is currently
+   * IsFullscreen() returns whether the instance is currently
    * displaying in fullscreen mode.
    *
+   * @param resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_View</code> resource.
+   *
    * @return <code>PP_TRUE</code> if the instance is in full screen mode,
    * or <code>PP_FALSE</code> if it's not or the resource is invalid.
    */
   PP_Bool (*IsFullscreen)(PP_Resource resource);
   /**
-   * <code>IsVisible()</code> returns whether the instance is plausibly
-   * visible to the user. You should use this flag to throttle or stop updates
-   * for invisible plugins.
+   * IsVisible() determines whether the module instance might be visible to
+   * the user. For example, the Chrome window could be minimized or another
+   * window could be over it. In both of these cases, the module instance
+   * would not be visible to the user, but IsVisible() will return true.
    *
-   * Thie measure incorporates both whether the instance is scrolled into
-   * view (whether the clip rect is nonempty) and whether the page is plausibly
-   * visible to the user (<code>IsPageVisible()</code>).
+   * Use the result to speed up or stop updates for invisible module
+   * instances.
    *
-   * @return <code>PP_TRUE</code> if the instance is plausibly visible to the
+   * This function performs the duties of GetRect() (determining whether the
+   * module instance is scrolled into view and the clip rectangle is nonempty)
+   * and IsPageVisible() (whether the page is visible to the user).
+   *
+   * @param resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_View</code> resource.
+   *
+   * @return <code>PP_TRUE</code> if the instance might be visible to the
    * user, <code>PP_FALSE</code> if it is definitely not visible.
    */
   PP_Bool (*IsVisible)(PP_Resource resource);
   /**
-   * <code>IsPageVisible()</code> determines if the page that contains the
-   * instance is visible. The most common cause of invisible pages is that
+   * IsPageVisible() determines if the page that contains the module instance
+   * is visible. The most common cause of invisible pages is that
    * the page is in a background tab in the browser.
    *
-   * Most applications should use <code>IsVisible()</code> rather than
-   * this function since the instance could be scrolled off of a visible
-   * page, and this function will still return true. However, depending on
-   * how your plugin interacts with the page, there may be certain updates
-   * that you may want to perform when the page is visible even if your
-   * specific instance isn't.
+   * Most applications should use IsVisible() instead of this function since
+   * the module instance could be scrolled off of a visible page, and this
+   * function will still return true. However, depending on how your module
+   * interacts with the page, there may be certain updates that you may want to
+   * perform when the page is visible even if your specific module instance is
+   * not visible.
+   *
+   * @param resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_View</code> resource.
    *
    * @return <code>PP_TRUE</code> if the instance is plausibly visible to the
    * user, <code>PP_FALSE</code> if it is definitely not visible.
    */
   PP_Bool (*IsPageVisible)(PP_Resource resource);
   /**
-   * <code>GetClipRect()</code> returns the clip rectangle relative to the
-   * upper left corner of the instance. This rectangle indicates which parts of
-   * the instance are scrolled into view.
-   *
-   * If the instance is scrolled off the view, the return value will be
-   * (0, 0, 0, 0). This clip rect does <i>not</i> take into account page
-   * visibility. This means if the instance is scrolled into view but the page
-   * itself is in an invisible tab, the return rect will contain the visible
-   * rect assuming the page was visible. See <code>IsPageVisible()</code> and
-   * <code>IsVisible()</code> if you want to handle this case.
-   *
-   * Most applications will not need to worry about the clip. The recommended
-   * behavior is to do full updates if the instance is visible as determined by
-   * <code>IsVisible()</code> and do no updates if not.
+   * GetClipRect() returns the clip rectangle relative to the upper-left corner
+   * of the module instance. This rectangle indicates the portions of the module
+   * instance that are scrolled into view.
+   *
+   * If the module instance is scrolled off the view, the return value will be
+   * (0, 0, 0, 0). This clip rectangle does <i>not</i> take into account page
+   * visibility. Therefore, if the module instance is scrolled into view, but
+   * the page itself is on a tab that is not visible, the return rectangle will
+   * contain the visible rectangle as though the page were visible. Refer to
+   * IsPageVisible() and IsVisible() if you want to account for page
+   * visibility.
+   *
+   * Most applications will not need to worry about the clip rectangle. The
+   * recommended behavior is to do full updates if the module instance is
+   * visible, as determined by IsVisible(), and do no updates if it is not
+   * visible.
    *
    * However, if the cost for computing pixels is very high for your
-   * application or the pages you're targeting frequently have very large
-   * instances with small visible portions, you may wish to optimize further.
-   * In this case, the clip rect will tell you which parts of the plugin to
-   * update.
+   * application, or the pages you're targeting frequently have very large
+   * module instances with small visible portions, you may wish to optimize
+   * further. In this case, the clip rectangle will tell you which parts of
+   * the module to update.
    *
    * Note that painting of the page and sending of view changed updates
    * happens asynchronously. This means when the user scrolls, for example,
-   * it is likely that the previous backing store of the instance will be used
-   * for the first paint, and will be updated later when your application
-   * generates new content with the new clip. This may cause flickering at the
-   * boundaries when scrolling. If you do choose to do partial updates, you may
-   * want to think about what color the invisible portions of your backing
-   * store contain (be it transparent or some background color) or to paint
-   * a certain region outside the clip to reduce the visual distraction when
-   * this happens.
+   * it is likely that the previous backing store of the module instance will
+   * be used for the first paint, and will be updated later when your
+   * application generates new content with the new clip. This may cause
+   * flickering at the boundaries when scrolling. If you do choose to do
+   * partial updates, you may want to think about what color the invisible
+   * portions of your backing store contain (be it transparent or some
+   * background color) or to paint a certain region outside the clip to reduce
+   * the visual distraction when this happens.
+   *
+   * @param resource A <code>PP_Resource</code> corresponding to a
+   * <code>PPB_View</code> resource.
    *
    * @param clip Output argument receiving the clip rect on success.
    *