Some more documentation about contexts and action containers.

src/plugins/coreplugin/actionmanager/actioncontainer.cpp

@@ -51,63 +51,98 @@ using namespace Core::Internal;
 
     \brief The ActionContainer class represents a menu or menu bar in Qt Creator.
 
+    You don't create instances of this class directly, but instead use the
+    \l{ActionManager::createMenu()}
+    and \l{ActionManager::createMenuBar()} methods.
+    Retrieve existing action containers for an ID with
+    \l{ActionManager::actionContainer()}.
 
-*/
+    Within a menu or menu bar you can group menus and items together by defining groups
+    (the order of the groups is defined by the order of the \l{ActionContainer::appendGroup()} calls), and
+    adding menus/actions to these groups. If no custom groups are defined, an action container
+    has three default groups \c{Core::Constants::G_DEFAULT_ONE}, \c{Core::Constants::G_DEFAULT_TWO}
+    and \c{Core::Constants::G_DEFAULT_THREE}.
 
-/*!
+    You can define if the menu represented by this action container should automatically disable
-    \enum ActionContainer::ContainerType
+    or hide whenever it only contains disabled items and submenus by setting the corresponding
+    \l{ActionContainer::setEmptyAction()}{EmptyAction}.
 */
 
 /*!
     \enum ActionContainer::EmptyAction
+    Defines what happens when the represented menu is empty or contains only disabled/invisible items.
+    \omitvalue EA_Mask
+    \value EA_None
+        The menu will still be visible and active.
+    \value EA_Disable
+        The menu will be visible but disabled.
+    \value EA_Hide
+        The menu will not be visible until the state of the subitems change.
 */
 
 /*!
-    \fn virtual ActionContainer::setEmptyAction(EmptyAction ea)
+    \fn ActionContainer::setEmptyAction(EmptyAction disableOrHide)
+    Defines if the menu represented by this action container should automatically \a disableOrHide
+    whenever it only contains disabled items and submenus.
+    \sa ActionContainer::EmptyAction
 */
 
 /*!
-    \fn virtual int ActionContainer::id() const
+    \fn int ActionContainer::id() const
+    \internal
 */
 
 /*!
-    \fn virtual ContainerType ActionContainer::type() const
+    \fn QMenu *ActionContainer::menu() const
+    Returns the QMenu instance that is represented by this action container, or
+    0 if this action container represents a menu bar.
 */
 
 /*!
-    \fn virtual QMenu *ActionContainer::menu() const
+    \fn QMenuBar *ActionContainer::menuBar() const
+    Returns the QMenuBar instance that is represented by this action container, or
+    0 if this action container represents a menu.
 */
 
 /*!
-    \fn virtual QToolBar *ActionContainer::toolBar() const
+    \fn QAction *ActionContainer::insertLocation(const QString &group) const
+    Returns an action representing the \a group,
+    that could be used with \c{QWidget::insertAction}.
 */
 
 /*!
-    \fn virtual QMenuBar *ActionContainer::menuBar() const
+    \fn void ActionContainer::appendGroup(const QString &identifier)
+    Adds a group with the given \a identifier to the action container. Using groups
+    you can segment your action container into logical parts and add actions and
+    menus directly to these parts.
+    \sa addAction()
+    \sa addMenu()
 */
 
 /*!
-    \fn virtual QAction *ActionContainer::insertLocation(const QString &group) const
+    \fn void ActionContainer::addAction(Core::Command *action, const QString &group)
+    Add the \a action as a menu item to this action container. The action is added as the
+    last item of the specified \a group.
+    \sa appendGroup()
+    \sa addMenu()
 */
 
 /*!
-    \fn virtual void ActionContainer::appendGroup(const QString &group, bool global)
+    \fn void ActionContainer::addMenu(Core::ActionContainer *menu, const QString &group)
+    Add the \a menu as a submenu to this action container. The menu is added as the
+    last item of the specified \a group.
+    \sa appendGroup()
+    \sa addAction()
 */
 
 /*!
-    \fn virtual void ActionContainer::addAction(Core::Command *action, const QString &group)
+    \fn bool ActionContainer::update()
+    \internal
 */
 
 /*!
-    \fn virtual void ActionContainer::addMenu(Core::ActionContainer *menu, const QString &group)
+    \fn ActionContainer::~ActionContainer()
-*/
+    \internal
-
-/*!
-    \fn virtual bool ActionContainer::update()
-*/
-
-/*!
-    \fn virtual ActionContainer::~ActionContainer()
 */
 
 // ---------- ActionContainerPrivate ------------

src/plugins/coreplugin/actionmanager/actionmanager.cpp

@@ -64,16 +64,32 @@ namespace {
     can specify all his keyboard shortcuts, and to provide a solution for actions that should
     behave differently in different contexts (like the copy/replace/undo/redo actions).
 
-    All actions that are registered with the same string id (but different context lists)
+    \section1 Contexts
+
+    All actions that are registered with the same string ID (but different context lists)
     are considered to be overloads of the same command, represented by an instance
     of the Command class.
+    Exactly only one of the registered actions with the same ID is active at any time.
+    Which action this is, is defined by the context list that the actions were registered
+    with:
+
+    If the current focus widget was registered via \l{ICore::addContextObject()},
+    all the contexts returned by its IContext object are active. In addition all
+    contexts set via \l{ICore::addAdditionalContext()} are active as well. If one
+    of the actions was registered for one of these active contexts, it is the one
+    active action, and receives \c triggered and \c toggled signals. Also the
+    appearance of the visible action for this ID might be adapted to this
+    active action (depending on the settings of the corresponding \l{Command} object).
+
     The action that is visible to the user is the one returned by Command::action().
     If you provide yourself a user visible representation of your action you need
     to use Command::action() for this.
     When this action is invoked by the user,
     the signal is forwarded to the registered action that is valid for the current context.
 
-    So to register a globally active action "My Action"
+    \section1 Registering Actions
+
+    To register a globally active action "My Action"
     put the following in your plugin's IPlugin::initialize method:
     \code
         Core::ActionManager *am = Core::ICore::instance()->actionManager();
@@ -96,7 +112,7 @@ namespace {
     Also use the ActionManager to add items to registered
     action containers like the applications menu bar or menus in that menu bar.
     To do this, you register your action via the
-    registerAction methods, get the action container for a specific id (like specified in
+    registerAction methods, get the action container for a specific ID (like specified in
     the Core::Constants namespace) with a call of
     actionContainer(const QString&) and add your command to this container.
 
@@ -105,15 +121,15 @@ namespace {
         am->actionContainer(Core::M_TOOLS)->addAction(cmd);
     \endcode
 
-    Important guidelines:
+    \section1 Important Guidelines:
     \list
     \o Always register your actions and shortcuts!
-    \o Register your actions and shortcuts during your plugin's IPlugin::initialize
+    \o Register your actions and shortcuts during your plugin's \l{ExtensionSystem::IPlugin::initialize()}
-       or IPlugin::extensionsInitialized methods, otherwise the shortcuts won't appear
+       or \l{ExtensionSystem::IPlugin::extensionsInitialized()} methods, otherwise the shortcuts won't appear
        in the keyboard settings dialog from the beginning.
-    \o When registering an action with cmd=registerAction(action, id, contexts) be sure to connect
+    \o When registering an action with \c{cmd=registerAction(action, id, contexts)} be sure to connect
-       your own action connect(action, SIGNAL...) but make cmd->action() visible to the user, i.e.
+       your own action \c{connect(action, SIGNAL...)} but make \c{cmd->action()} visible to the user, i.e.
-       widget->addAction(cmd->action()).
+       \c{widget->addAction(cmd->action())}.
     \o Use this class to add actions to the applications menus
     \endlist
 

src/plugins/coreplugin/actionmanager/command.cpp

@@ -37,9 +37,8 @@
     \class Core::Command
     \mainclass
 
-    \brief The class...
+    \brief The class Command represents an action like a menu item, tool button, or shortcut.
 
-    The Command interface...
 */
 
 /*!