More documentation on CreateBrowserModalDialogViews.

Give a little info about default buttons so that consumers think about
whether or not they're a good thing.

BUG=884831
R=pkasting@chromium.org

Change-Id: I9f65cfdfc349fb71a270973d416decd5528c8e88
Reviewed-on: https://chromium-review.googlesource.com/1251082Reviewed-by: Peter Kasting <pkasting@chromium.org>
Reviewed-by: Michael Wasserman <msw@chromium.org>
Commit-Queue: Greg Thompson <grt@chromium.org>
Cr-Commit-Position: refs/heads/master@{#595306}

components/constrained_window/constrained_window_views.h

@@ -78,6 +78,12 @@ views::Widget* CreateWebModalDialogViews(views::WidgetDelegate* dialog,
 // appropriately if |parent| is a valid browser window. Currently, |parent| may
 // be null for MODAL_TYPE_WINDOW, but that's a bug and callers shouldn't rely on
 // that working. See http://crbug.com/657293.
+// For dialogs that may appear without direct user interaction (i.e., that may
+// appear while a user is busily accomplishing some other task in the browser),
+// consider providing an override of GetDefaultDialogButton on |dialog| to
+// suppress the normal behavior of choosing a focused-by-default button. This is
+// especially important if the action of the default button has consequences on
+// the user's task at hand.
 views::Widget* CreateBrowserModalDialogViews(views::DialogDelegate* dialog,
                                              gfx::NativeWindow parent);