Pepper: Fix comments for PPB and PPP InputEvent.

The comments provided in PPB_InputEvent and PPP_InputEvent incorrectly describe
how handled events are delivered to handlers in web pages.

When a plugin handles an event, the event is not "bubbled" to any default
handlers. However, any listeners in a web page run before the event reaches the
plugin, so the plugin can't prevent any listeners from getting the event.

An attempt to make the implementation match the specification broke existing
plugins, so the only reasonable approach is to make the comments match the
behavior.

BUG=324352
R=dmichael@chromium.org

Review URL: https://codereview.chromium.org/228653006

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

5 files changed, 20 insertions, 24 deletions

diff --git a/ppapi/api/ppb_input_event.idl b/ppapi/api/ppb_input_event.idl
index d871a76..b9224fa 100644
--- a/ppapi/api/ppb_input_event.idl
+++ b/ppapi/api/ppb_input_event.idl
@@ -316,9 +316,7 @@ interface PPB_InputEvent {
    * (and only if) you do not request touch events.
    *
    * When requesting input events through this function, the events will be
-   * delivered and <i>not</i> bubbled to the page. This means that even if you
-   * aren't interested in the message, no other parts of the page will get
-   * a crack at the message.
+   * delivered and <i>not</i> bubbled to the default handlers.
    *
    * <strong>Example:</strong>
    * @code
@@ -353,8 +351,8 @@ interface PPB_InputEvent {
    * By default, no input events are delivered. In most cases you would
    * register to receive events by calling RequestInputEvents(). In some cases,
    * however, you may wish to filter events such that they can be bubbled up
-   * to the DOM. In this case, register for those classes of events using
-   * this function instead of RequestInputEvents().
+   * to the default handlers. In this case, register for those classes of
+   * events using this function instead of RequestInputEvents().
    *
    * Filtering input events requires significantly more overhead than just
    * delivering them to the instance. As such, you should only request
diff --git a/ppapi/api/ppp_input_event.idl b/ppapi/api/ppp_input_event.idl
index a7efb5b..97285c2 100644
--- a/ppapi/api/ppp_input_event.idl
+++ b/ppapi/api/ppp_input_event.idl
@@ -20,10 +20,10 @@ interface PPP_InputEvent {
    * PPB_InputEvent.RequestInputEvents() or RequestFilteringInputEvents(). By
    * default, no events are delivered.
    *
-   * If the event was handled, it will not be forwarded to the web page or
-   * browser. If it was not handled, it will bubble according to the normal
-   * rules. So it is important that an instance respond accurately with whether
-   * event propagation should continue.
+   * If the event was handled, it will not be forwarded to the default handlers
+   * in the web page.  If it was not handled, it may be dispatched to a default
+   * handler. So it is important that an instance respond accurately with
+   * whether event propagation should continue.
    *
    * Event propagation also controls focus. If you handle an event like a mouse
    * event, typically the instance will be given focus. Returning false from
diff --git a/ppapi/c/ppb_input_event.h b/ppapi/c/ppb_input_event.h
index 257d568..ca2bf15 100644
--- a/ppapi/c/ppb_input_event.h
+++ b/ppapi/c/ppb_input_event.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From ppb_input_event.idl modified Mon Dec 16 15:35:15 2013. */
+/* From ppb_input_event.idl modified Thu Apr  3 14:52:10 2014. */
 
 #ifndef PPAPI_C_PPB_INPUT_EVENT_H_
 #define PPAPI_C_PPB_INPUT_EVENT_H_
@@ -334,9 +334,7 @@ struct PPB_InputEvent_1_0 {
    * (and only if) you do not request touch events.
    *
    * When requesting input events through this function, the events will be
-   * delivered and <i>not</i> bubbled to the page. This means that even if you
-   * aren't interested in the message, no other parts of the page will get
-   * a crack at the message.
+   * delivered and <i>not</i> bubbled to the default handlers.
    *
    * <strong>Example:</strong>
    * @code
@@ -369,8 +367,8 @@ struct PPB_InputEvent_1_0 {
    * By default, no input events are delivered. In most cases you would
    * register to receive events by calling RequestInputEvents(). In some cases,
    * however, you may wish to filter events such that they can be bubbled up
-   * to the DOM. In this case, register for those classes of events using
-   * this function instead of RequestInputEvents().
+   * to the default handlers. In this case, register for those classes of
+   * events using this function instead of RequestInputEvents().
    *
    * Filtering input events requires significantly more overhead than just
    * delivering them to the instance. As such, you should only request
diff --git a/ppapi/c/ppp_input_event.h b/ppapi/c/ppp_input_event.h
index 76c32b2..4f3e017d9 100644
--- a/ppapi/c/ppp_input_event.h
+++ b/ppapi/c/ppp_input_event.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From ppp_input_event.idl modified Mon Dec 19 19:44:12 2011. */
+/* From ppp_input_event.idl modified Tue Apr  8 15:19:45 2014. */
 
 #ifndef PPAPI_C_PPP_INPUT_EVENT_H_
 #define PPAPI_C_PPP_INPUT_EVENT_H_
@@ -35,10 +35,10 @@ struct PPP_InputEvent_0_1 {
    * PPB_InputEvent.RequestInputEvents() or RequestFilteringInputEvents(). By
    * default, no events are delivered.
    *
-   * If the event was handled, it will not be forwarded to the web page or
-   * browser. If it was not handled, it will bubble according to the normal
-   * rules. So it is important that an instance respond accurately with whether
-   * event propagation should continue.
+   * If the event was handled, it will not be forwarded to the default handlers
+   * in the web page.  If it was not handled, it may be dispatched to a default
+   * handler. So it is important that an instance respond accurately with
+   * whether event propagation should continue.
    *
    * Event propagation also controls focus. If you handle an event like a mouse
    * event, typically the instance will be given focus. Returning false from
diff --git a/ppapi/cpp/instance.h b/ppapi/cpp/instance.h
index 6bf4e83..f255fd9 100644
--- a/ppapi/cpp/instance.h
+++ b/ppapi/cpp/instance.h
@@ -174,10 +174,10 @@ class Instance {
   /// RequestInputEvents() or RequestFilteringInputEvents(). By
   /// default, no events are delivered.
   ///
-  /// If the event was handled, it will not be forwarded to the web page or
-  /// browser. If it was not handled, it will bubble according to the normal
-  /// rules. So it is important that an instance respond accurately with whether
-  /// event propagation should continue.
+  /// If the event was handled, it will not be forwarded to any default
+  /// handlers. If it was not handled, it may be dispatched to a default
+  /// handler. So it is important that an instance respond accurately with
+  /// whether event propagation should continue.
   ///
   /// Event propagation also controls focus. If you handle an event like a mouse
   /// event, typically the instance will be given focus. Returning false from