Add a comment explaining a different failure mode of the Pepper file chooser.

ppapi/api/dev/ppb_file_chooser_dev.idl

 /* Copyright (c) 2012 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.
  */
 
 
 /**
  * This file defines the <code>PPB_FileChooser_Dev</code> interface.
  */
 
@@ skipping 58 matching lines @@
       [in] PP_Resource resource);
 
   /**
    * This function displays a previously created file chooser resource as a
    * dialog box, prompting the user to choose a file or files. This function
    * must be called in response to a user gesture, such as a mouse click or
    * touch event. The callback is called with PP_OK on successful completion
    * with a file (or files) selected, PP_ERROR_USERCANCEL if the user selected
    * no file, or another error code from pp_errors.h on failure.
    *
+   * <b>Subtle note:</b> This function will only work when the tab containing
+   * the plugin is visible. Show will fail if the tab is in the background.
+   * Since it's not normally possible to get input events while invisible, this
+   * is not an issue. But there is a race condition because events are
+   * processed asynchronously that authors should be aware of. If the user
+   * clicks and switches tabs very quickly, a plugin could believe the tab is
+   * visible while Chrome believes it is invisible and the Show() call will
+   * fail. This will not generally cause user confusion since the user will
+   * have switched tabs and will not want to see a file chooser from a
+   * different tab.
+   *
    * @param[in] chooser The file chooser resource.
    * @param[in] callback A <code>CompletionCallback</code> to be called after
    * the user has closed the file chooser dialog.
    *
    * @return PP_OK_COMPLETIONPENDING if request to show the dialog was
    * successful, another error code from pp_errors.h on failure.
    */
   [deprecate=0.6]
   int32_t Show(
       [in] PP_Resource chooser,
@@ skipping 16 matching lines @@
       [in] PP_Resource chooser);
 
   /**
    * This function displays a previously created file chooser resource as a
    * dialog box, prompting the user to choose a file or files. This function
    * must be called in response to a user gesture, such as a mouse click or
    * touch event. The callback is called with PP_OK on successful completion
    * with a file (or files) selected, PP_ERROR_USERCANCEL if the user selected
    * no file, or another error code from pp_errors.h on failure.
    *
+   * <b>Subtle note:</b> This function will only work when the tab containing
+   * the plugin is visible. Show() will fail if the tab is in the background.
+   * Since it's not normally possible to get input events while invisible, this
+   * is not normally an issue. But there is a race condition because events are
+   * processed asynchronously. If the user clicks and switches tabs very
+   * quickly, a plugin could believe the tab is visible while Chrome believes
+   * it is invisible and the Show() call will fail. This will not generally
+   * cause user confusion since the user will have switched tabs and will not
+   * want to see a file chooser from a different tab.
+   *
    * @param[in] chooser The file chooser resource.
    *
    * @param[in] output An output array which will receive PP_Resource(s)
    * identifying the <code>PPB_FileRef</code> objects that the user selected on
    * success.
    *
    * @param[in] callback A <code>CompletionCallback</code> to be called after
    * the user has closed the file chooser dialog.
    *
    * @return PP_OK_COMPLETIONPENDING if request to show the dialog was
    * successful, another error code from pp_errors.h on failure.
    */
   [version=0.6]
   int32_t Show([in] PP_Resource chooser,
                [in] PP_ArrayOutput output,
                [in] PP_CompletionCallback callback);
 };