MenuRunner: Add comment to specify blocking behavior on MacViews.

ui/views/controls/menu/menu_runner.h

 // 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.
 
 #ifndef UI_VIEWS_CONTROLS_MENU_MENU_RUNNER_H_
 #define UI_VIEWS_CONTROLS_MENU_MENU_RUNNER_H_
 
 #include <stdint.h>
 
 #include <memory>
@@ skipping 61 matching lines @@
     // The menu is a nested context menu. For example, click a folder on the
     // bookmark bar, then right click an entry to get its context menu.
     IS_NESTED = 1 << 1,
 
     // Used for showing a menu during a drop operation. This does NOT block the
     // caller, instead the delegate is notified when the menu closes via the
     // DropMenuClosed method.
     FOR_DROP = 1 << 2,
 
     // The menu is a context menu (not necessarily nested), for example right
-    // click on a link on a website in the browser.
+    // click on a link on a website in the browser. On Mac(Views), this is
+    // displayed using a native NSMenu and hence is blocking.
     CONTEXT_MENU = 1 << 3,
 
-    // The menu should behave like a Windows native Combobox dropdow menu.
-    // This behavior includes accepting the pending item and closing on F4.
+    // The menu should behave like a Windows native Combobox dropdow menu. This
+    // behavior includes accepting the pending item and closing on F4. On
+    // Mac(Views), this is displayed using a native NSMenu and hence is
+    // blocking.
     COMBOBOX = 1 << 4,
 
     // A child view is performing a drag-and-drop operation, so the menu should
     // stay open (even if it doesn't receive drag updated events). In this case,
     // the caller is responsible for closing the menu upon completion of the
     // drag-and-drop.
     NESTED_DRAG = 1 << 5,
 
     // Used for showing a menu which does NOT block the caller. Instead the
-    // delegate is notified when the menu closes via OnMenuClosed.
+    // delegate is notified when the menu closes via OnMenuClosed. On
+    // Mac(Views), this is ignored for the CONTEXT_MENU and COMBOBOX run types.
     ASYNC = 1 << 6,
   };
 
   enum RunResult {
     // Indicates RunMenuAt is returning because the MenuRunner was deleted.
     MENU_DELETED,
 
     // Indicates RunMenuAt returned and MenuRunner was not deleted.
     NORMAL_EXIT
   };
 
   // Creates a new MenuRunner, which may use a native menu if available.

[tapted, 2017/01/17 21:55:20]

This comment already mentions native menus. So perhaps a note here is best. Like

Note that with a native menu (e.g. on Mac), the ASYNC flag in |run_types| may be
ignored. See http://crbug.com/XXXXXX

   // |run_types| is a bitmask of RunTypes. If provided,
   // |on_menu_closed_callback| is invoked when the menu is closed.
   MenuRunner(ui::MenuModel* menu_model,
              int32_t run_types,
              const base::Closure& on_menu_closed_callback = base::Closure());
 
   // Creates a runner for a custom-created toolkit-views menu.
   MenuRunner(MenuItemView* menu, int32_t run_types);

[tapted, 2017/01/17 21:55:20]

So I think using this constructor, run_types on Mac will work correctly - so
documenting the enum probably is misleading.

[karandeepb, 2017/01/19 04:18:15]

Oh yeah, you are correct. Did not see this constructor.

   ~MenuRunner();
 
   // Runs the menu. If this returns MENU_DELETED the method is returning
   // because the MenuRunner was deleted.
   // Typically callers should NOT do any processing if this returns
   // MENU_DELETED.
   // If |anchor| uses a |BUBBLE_..| type, the bounds will get determined by
   // using |bounds| as the thing to point at in screen coordinates.
   RunResult RunMenuAt(Widget* parent,
                       MenuButton* button,
@@ skipping 46 matching lines @@
 
  protected:
   DisplayChangeListener() {}
 };
 
 }  // namespace internal
 
 }  // namespace views
 
 #endif  // UI_VIEWS_CONTROLS_MENU_MENU_RUNNER_H_