Doc: Fix QDoc warnings issued for Core plugin ActionManager docs

Fix warnings for: - ActionContainer - ActionManager - Command - CommandButton - CommandMappings - CommandsFile Task-number: QTCREATORBUG-23584 Change-Id: I3c7903e054d43143885d67d64309d1ae4429de2c Reviewed-by: Eike Ziller <eike.ziller@qt.io>
2020-02-12 13:26:28 +01:00
parent e4df228522
commit 1793d6ac00
6 changed files with 159 additions and 44 deletions
--- a/src/plugins/coreplugin/actionmanager/actioncontainer.cpp
+++ b/src/plugins/coreplugin/actionmanager/actioncontainer.cpp
@@ -42,13 +42,13 @@ Q_DECLARE_METATYPE(Core::Internal::MenuActionContainer*)
 using namespace Utils;

 namespace Core {
-namespace Internal {

 /*!
-    \class ActionContainer
-    \mainclass
+    \class Core::ActionContainer
+    \ingroup mainclasses
+    \inmodule QtCreator

-    \brief The ActionContainer class represents a menu or menu bar in Qt Creator.
+    \brief The ActionContainer class represents a menu or menu bar in \QC.

    You don't create instances of this class directly, but instead use the
    \l{ActionManager::createMenu()}, \l{ActionManager::createMenuBar()} and
@@ -58,23 +58,25 @@ namespace Internal {

    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
+    adding menus or 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
-    or hide whenever it only contains disabled items and submenus by setting the corresponding
+    You can specify whether the menu represented by this action container should
+    be automatically disabled or hidden whenever it only contains disabled items
+    and submenus by setting the corresponding
    \l{ActionContainer::setOnAllDisabledBehavior()}{OnAllDisabledBehavior}. The default is
    ActionContainer::Disable for menus, and ActionContainer::Show for menu bars.
 */

 /*!
    \enum ActionContainer::OnAllDisabledBehavior
-    Defines what happens when the represented menu is empty or contains only disabled/invisible items.
+    Defines what happens when the represented menu is empty or contains only
+    disabled or invisible items.
    \value Disable
        The menu will be visible but disabled.
    \value Hide
-        The menu will not be visible until the state of the subitems change.
+        The menu will not be visible until the state of the subitems changes.
    \value Show
        The menu will still be visible and active.
 */
@@ -90,7 +92,7 @@ namespace Internal {

 /*!
    \fn ActionContainer::onAllDisabledBehavior() const
-    Returns the \a behavior of the menu represented by this action container for the case
+    Returns the behavior of the menu represented by this action container for the case
    whenever it only contains disabled items and submenus.
    The default is ActionContainer::Disable for menus, and ActionContainer::Show for menu bars.
    \sa ActionContainer::OnAllDisabledBehavior
@@ -122,9 +124,10 @@ namespace Internal {

 /*!
    \fn void ActionContainer::appendGroup(Id group)
-    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.
+    Adds \a group to the action container.
+
+    Use groups to segment your action container into logical parts. You can add
+    actions and menus directly into groups.
    \sa addAction()
    \sa addMenu()
 */
@@ -145,6 +148,45 @@ namespace Internal {
    \sa addAction()
 */

+/*!
+    \fn void ActionContainer::addMenu(ActionContainer *before, ActionContainer *menu)
+    Add \a menu as a submenu to this action container before the menu specified
+    by \a before.
+    \sa appendGroup()
+    \sa addAction()
+*/
+
+/*!
+    \fn ActionContainer::clear()
+
+    Clears this menu and submenus from all actions and submenus. However, does
+    does not destroy the submenus and commands, just removes them from their
+    parents.
+*/
+
+/*!
+    \fn ActionContainer::insertGroup(Id before, Id group)
+
+    Inserts \a group to the action container before the group specified by
+    \a before.
+*/
+
+/*!
+    \fn virtual Utils::TouchBar *ActionContainer::touchBar() const
+
+    Returns the touch bar that is represented by this action container.
+*/
+
+/*!
+    \fn ActionContainer::addSeparator(const Context &context, Id group, QAction **outSeparator)
+
+    Adds a separator to the end of the given \a group to the action container,
+    which is enabled for a given \a context. Returns the created separator
+    action, \a outSeparator.
+*/
+
+namespace Internal {
+
 // ---------- ActionContainerPrivate ------------

 /*!
@@ -293,15 +335,6 @@ void ActionContainerPrivate::addMenu(ActionContainer *before, ActionContainer *m
    scheduleUpdate();
 }

-/*!
- * Adds a separator to the end of the given \a group to the action container, which is enabled
- * for a given \a context. The created separator action is returned through \a outSeparator.
- *
- * Returns the created Command for the separator.
- */
-/*! \a context \a group \a outSeparator
- * \internal
- */
 Command *ActionContainerPrivate::addSeparator(const Context &context, Id group, QAction **outSeparator)
 {
    static int separatorIdCount = 0;
@@ -648,6 +681,11 @@ bool TouchBarActionContainer::updateInternal()

 } // namespace Internal

+/*!
+    Adds a separator to the end of \a group to the action container.
+
+    Returns the created separator.
+*/
 Command *ActionContainer::addSeparator(Id group)
 {
    static const Context context(Constants::C_GLOBAL);
--- a/src/plugins/coreplugin/actionmanager/actionmanager.cpp
+++ b/src/plugins/coreplugin/actionmanager/actionmanager.cpp
@@ -52,7 +52,7 @@ using namespace Core::Internal;

 /*!
    \class Core::ActionManager
-    \mainclass
+    \ingroup mainclasses
    \inmodule QtCreator

    \brief The ActionManager class is responsible for registration of menus and
@@ -60,10 +60,10 @@ using namespace Core::Internal;

    The ActionManager is the central bookkeeper of actions and their shortcuts and layout.
    It is a singleton containing mostly static functions. If you need access to the instance,
-    e.g. for connecting to signals, is its ActionManager::instance() function.
+    e.g. for connecting to signals, call its ActionManager::instance() function.

-    The main reasons for the need of this class is to provide a central place where the user
-    can specify all his keyboard shortcuts, and to provide a solution for actions that should
+    The main reasons for the need of this class is to provide a central place where the users
+    can specify all their keyboard shortcuts, and to provide a solution for actions that should
    behave differently in different contexts (like the copy/replace/undo/redo actions).

    \section1 Contexts
@@ -147,7 +147,7 @@ using namespace Core::Internal;
 */

 /*!
-    \fn void ActionManager::commandAdded(const QString &id)
+    \fn void ActionManager::commandAdded(Core::Id id)

    Emitted when a command (with the \a id) is added.
 */
@@ -262,7 +262,7 @@ ActionContainer *ActionManager::createTouchBar(Id id, const QIcon &icon, const Q
    for the currently active context.
    If the optional \a context argument is not specified, the global context
    will be assumed.
-    A scriptable action can be called from a script without the need for the user
+    A \a scriptable action can be called from a script without the need for the user
    to interact with it.
 */
 Command *ActionManager::registerAction(QAction *action, Id id, const Context &context, bool scriptable)
@@ -356,7 +356,7 @@ void ActionManager::unregisterAction(QAction *action, Id id)

 /*!
    Handles the display of the used shortcuts in the presentation mode. The presentation mode is
-    enabled when starting \QC with the command line argument \c{-presentationMode}. In the
+    \a enabled when starting \QC with the command line argument \c{-presentationMode}. In the
    presentation mode, \QC displays any pressed shortcut in a grey box.
 */
 void ActionManager::setPresentationModeEnabled(bool enabled)
@@ -377,11 +377,19 @@ void ActionManager::setPresentationModeEnabled(bool enabled)
    d->m_presentationModeEnabled = enabled;
 }

+/*!
+    Returns whether presentation mode is enabled.
+
+    \sa setPresentationModeEnabled
+*/
 bool ActionManager::isPresentationModeEnabled()
 {
    return d->m_presentationModeEnabled;
 }

+/*!
+    \internal
+*/
 QString ActionManager::withNumberAccelerator(const QString &text, const int number)
 {
    if (Utils::HostOsInfo::isMacHost() || number > 9)
--- a/src/plugins/coreplugin/actionmanager/command.cpp
+++ b/src/plugins/coreplugin/actionmanager/command.cpp
@@ -40,9 +40,11 @@

 /*!
    \class Core::Command
-    \mainclass
+    \inmodule QtCreator
+    \ingroup mainclasses

    \brief The Command class represents an action, such as a menu item, tool button, or shortcut.
+
    You do not create Command objects directly, but use \l{ActionManager::registerAction()}
    to register an action and retrieve a Command. The Command object represents the user visible
    action and its properties. If multiple actions are registered with the same ID (but
@@ -69,13 +71,12 @@
    This enum defines how the user visible action is updated when the active action changes.
    The default is to update the enabled and visible state, and to disable the
    user visible action when there is no active action.
-    \omitvalue CA_Mask
    \value CA_UpdateText
        Also update the actions text.
    \value CA_UpdateIcon
        Also update the actions icon.
    \value CA_Hide
-        When there is no active action, hide the user "visible" action, instead of just
+        When there is no active action, hide the user-visible action, instead of just
        disabling it.
    \value CA_NonConfigurable
        Flag to indicate that the keyboard shortcut of this Command should not be
@@ -150,6 +151,12 @@
    no active action for the current context.
 */

+/*!
+    \fn Context Command::context() const
+
+    Returns the context for this command.
+*/
+
 /*!
    \fn void Command::setAttribute(CommandAttribute attribute)
    Adds \a attribute to the attributes of this Command.
@@ -187,18 +194,48 @@

 /*!
    \fn bool Command::isScriptable(const Context &) const
-    Returns whether the Command is scriptable for the given context.
-    A scriptable command can be called from a script without the need for the user to
-    interact with it.
+    \internal
+
+    Returns whether the Command is scriptable.
+*/
+
+/*!
+    \fn void Command::activeStateChanged()
+
+    This signal is emitted when the active state of the command changes.
+*/
+
+/*!
+    \fn virtual void Command::setTouchBarText(const QString &text)
+
+    Sets the text for the action on the touch bar to \a text.
+*/
+
+/*!
+    \fn virtual QString Command::touchBarText() const
+
+    Returns the text for the action on the touch bar.
+*/
+
+/*!
+    \fn virtual void Command::setTouchBarIcon(const QIcon &icon)
+
+    Sets the icon for the action on the touch bar to \a icon.
+*/
+
+/*! \fn virtual QIcon Command::touchBarIcon() const
+
+    Returns the icon for the action on the touch bar.
+*/
+
+/*! \fn virtual QAction *Command::touchBarAction() const
+
+    Adds an action to the touch bar.
 */

 namespace Core {
 namespace Internal {

-/*!
-  \class Action
-  \internal
-*/
 Action::Action(Id id)
    : m_attributes({}),
      m_id(id),
@@ -453,6 +490,10 @@ QAction *Action::touchBarAction() const

 } // namespace Internal

+/*!
+    Appends the keyboard shortcut that is currently assigned to the action \a a
+    to its tool tip.
+*/
 void Command::augmentActionWithShortcutToolTip(QAction *a) const
 {
    a->setToolTip(stringWithAppendedShortcut(a->text()));
@@ -464,6 +505,11 @@ void Command::augmentActionWithShortcutToolTip(QAction *a) const
    });
 }

+/*!
+    Returns a tool button for \a action.
+
+    Appends the keyboard shortcut \a cmd to the tool tip of the action.
+*/
 QToolButton *Command::toolButtonWithAppendedShortcut(QAction *action, Command *cmd)
 {
    auto button = new QToolButton;
--- a/src/plugins/coreplugin/actionmanager/commandbutton.cpp
+++ b/src/plugins/coreplugin/actionmanager/commandbutton.cpp
@@ -34,6 +34,7 @@ using namespace Core;

 /*!
    \class Core::CommandButton
+    \inmodule QtCreator

    \brief The CommandButton class is a tool button associated with one of
    the registered Command objects.
@@ -42,12 +43,23 @@ using namespace Core;
    key sequence which is automatically updated when user changes it.
 */

+/*!
+    \property CommandButton::toolTipBase
+    \brief The tool tip base for the command button.
+*/
+
+/*!
+    \internal
+*/
 CommandButton::CommandButton(QWidget *parent)
    : QToolButton(parent)
    , m_command(nullptr)
 {
 }

+/*!
+    \internal
+*/
 CommandButton::CommandButton(Id id, QWidget *parent)
    : QToolButton(parent)
    , m_command(nullptr)
@@ -55,6 +67,9 @@ CommandButton::CommandButton(Id id, QWidget *parent)
    setCommandId(id);
 }

+/*!
+    Sets the ID of the command associated with this tool button to \a id.
+*/
 void CommandButton::setCommandId(Id id)
 {
    if (m_command)
--- a/src/plugins/coreplugin/actionmanager/commandmappings.cpp
+++ b/src/plugins/coreplugin/actionmanager/commandmappings.cpp
@@ -123,6 +123,12 @@ public:

 } // namespace Internal

+/*!
+    \class Core::CommandMappings
+    \inmodule QtCreator
+    \internal
+*/
+
 CommandMappings::CommandMappings(QWidget *parent)
    : QWidget(parent), d(new Internal::CommandMappingsPrivate(this))
 {
--- a/src/plugins/coreplugin/actionmanager/commandsfile.cpp
+++ b/src/plugins/coreplugin/actionmanager/commandsfile.cpp
@@ -64,13 +64,15 @@ Context::Context() :
 }

 /*!
-    \class CommandsFile
+    \class Core::Internal::CommandsFile
+    \internal
+    \inmodule QtCreator
    \brief The CommandsFile class provides a collection of import and export commands.
    \inheaderfile commandsfile.h
 */

 /*!
-    ...
+    \internal
 */
 CommandsFile::CommandsFile(const QString &filename)
    : m_filename(filename)
@@ -79,7 +81,7 @@ CommandsFile::CommandsFile(const QString &filename)
 }

 /*!
-    ...
+    \internal
 */
 QMap<QString, QKeySequence> CommandsFile::importCommands() const
 {
@@ -123,7 +125,7 @@ QMap<QString, QKeySequence> CommandsFile::importCommands() const
 }

 /*!
-    ...
+    \internal
 */

 bool CommandsFile::exportCommands(const QList<ShortcutItem *> &items)