views: document macOS enter-accepts-dialog behavior

The way it's implemented is very non-obvious and hard to find via
code search, so add a comment explaining it and an explicit xref to
the involved PlatformStyle constant.

Bug: None
Change-Id: Ia1756752d403cffac434d6249897b2d5d35eeba0
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2342572
Commit-Queue: Elly Fong-Jones <ellyjones@chromium.org>
Reviewed-by: Peter Kasting <pkasting@chromium.org>
Reviewed-by: Peter Boström <pbos@chromium.org>
Cr-Commit-Position: refs/heads/master@{#796491}

ui/views/controls/button/button.cc

@@ -259,6 +259,10 @@ Button::KeyClickAction Button::GetKeyClickActionForEvent(
     const ui::KeyEvent& event) {
   if (event.key_code() == ui::VKEY_SPACE)
     return PlatformStyle::kKeyClickActionOnSpace;
+  // Note that default buttons also have VKEY_RETURN installed as an accelerator
+  // in LabelButton::SetIsDefault(). On platforms where
+  // PlatformStyle::kReturnClicksFocusedControl, the logic here will take
+  // precedence over that.
   if (event.key_code() == ui::VKEY_RETURN &&
       PlatformStyle::kReturnClicksFocusedControl)
     return KeyClickAction::kOnKeyPress;

ui/views/controls/button/label_button.cc

@@ -188,6 +188,11 @@ void LabelButton::SetIsDefault(bool is_default) {
   if (GetIsDefault() == is_default)
     return;
   is_default_ = is_default;
+
+  // The default button has an accelerator for VKEY_RETURN, which clicks it.
+  // Note that if PlatformStyle::kReturnClicksFocusedControl is true and another
+  // button is focused, that button's VKEY_RETURN handler will take precedence.
+  // See Button::GetKeyClickActionForEvent().
   ui::Accelerator accel(ui::VKEY_RETURN, ui::EF_NONE);
   if (is_default)
     AddAccelerator(accel);