Commit 120bf88e authored by Leena Miettinen's avatar Leena Miettinen Committed by Eike Ziller
Browse files

Doc: edit coreplugin docs



Remove \brief commands for functions.
Use standard wording for QDoc commands.
Fix style and grammar issues.
Use the \a command instead of the \c command for attributes
in function descriptions.
Do not use \returns, because it does not exist.

Change-Id: Icd32b519670cb376e246bab3a58fe7e98d2529ea
Reviewed-by: default avatarEike Ziller <eike.ziller@digia.com>
parent 65f05881
...@@ -169,7 +169,7 @@ ActionManager *ActionManager::instance() ...@@ -169,7 +169,7 @@ ActionManager *ActionManager::instance()
} }
/*! /*!
\brief Creates a new menu with the given \a id. Creates a new menu with the given \a id.
Returns a new ActionContainer that you can use to get the QMenu instance Returns a new ActionContainer that you can use to get the QMenu instance
or to add menu items to the menu. The ActionManager owns or to add menu items to the menu. The ActionManager owns
...@@ -196,7 +196,7 @@ ActionContainer *ActionManager::createMenu(Id id) ...@@ -196,7 +196,7 @@ ActionContainer *ActionManager::createMenu(Id id)
} }
/*! /*!
\brief Creates a new menu bar with the given \a id. Creates a new menu bar with the given \a id.
Returns a new ActionContainer that you can use to get the QMenuBar instance Returns a new ActionContainer that you can use to get the QMenuBar instance
or to add menus to the menu bar. The ActionManager owns or to add menus to the menu bar. The ActionManager owns
...@@ -221,7 +221,7 @@ ActionContainer *ActionManager::createMenuBar(Id id) ...@@ -221,7 +221,7 @@ ActionContainer *ActionManager::createMenuBar(Id id)
} }
/*! /*!
\brief Makes an \a action known to the system under the specified \a id. Makes an \a action known to the system under the specified \a id.
Returns a command object that represents the action in the application and is Returns a command object that represents the action in the application and is
owned by the ActionManager. You can register several actions with the owned by the ActionManager. You can register several actions with the
...@@ -243,7 +243,7 @@ Command *ActionManager::registerAction(QAction *action, Id id, const Context &co ...@@ -243,7 +243,7 @@ Command *ActionManager::registerAction(QAction *action, Id id, const Context &co
} }
/*! /*!
\brief Makes a \a shortcut known to the system under the specified \a id. Makes a \a shortcut known to the system under the specified \a id.
Returns a command object that represents the shortcut in the application and is Returns a command object that represents the shortcut in the application and is
owned by the ActionManager. You can registered several shortcuts with the owned by the ActionManager. You can registered several shortcuts with the
...@@ -292,7 +292,7 @@ Command *ActionManager::registerShortcut(QShortcut *shortcut, Id id, const Conte ...@@ -292,7 +292,7 @@ Command *ActionManager::registerShortcut(QShortcut *shortcut, Id id, const Conte
} }
/*! /*!
\brief Returns the Command object that is known to the system Returns the Command object that is known to the system
under the given \a id. under the given \a id.
\sa ActionManager::registerAction() \sa ActionManager::registerAction()
...@@ -310,7 +310,7 @@ Command *ActionManager::command(Id id) ...@@ -310,7 +310,7 @@ Command *ActionManager::command(Id id)
} }
/*! /*!
\brief Returns the IActionContainter object that is know to the system Returns the IActionContainter object that is know to the system
under the given \a id. under the given \a id.
\sa ActionManager::createMenu() \sa ActionManager::createMenu()
...@@ -329,7 +329,7 @@ ActionContainer *ActionManager::actionContainer(Id id) ...@@ -329,7 +329,7 @@ ActionContainer *ActionManager::actionContainer(Id id)
} }
/*! /*!
* \brief Returns all commands that have been registered. * Returns all commands that have been registered.
*/ */
QList<Command *> ActionManager::commands() QList<Command *> ActionManager::commands()
{ {
...@@ -341,7 +341,7 @@ QList<Command *> ActionManager::commands() ...@@ -341,7 +341,7 @@ QList<Command *> ActionManager::commands()
} }
/*! /*!
\brief Removes the knowledge about an \a action under the specified \a id. Removes the knowledge about an \a action under the specified \a id.
Usually you do not need to unregister actions. The only valid use case for unregistering Usually you do not need to unregister actions. The only valid use case for unregistering
actions, is for actions that represent user definable actions, like for the custom Locator actions, is for actions that represent user definable actions, like for the custom Locator
...@@ -372,7 +372,7 @@ void ActionManager::unregisterAction(QAction *action, Id id) ...@@ -372,7 +372,7 @@ void ActionManager::unregisterAction(QAction *action, Id id)
} }
/*! /*!
\brief Removes the knowledge about a shortcut under the specified \a id. Removes the knowledge about a shortcut under the specified \a id.
Usually you do not need to unregister shortcuts. The only valid use case for unregistering Usually you do not need to unregister shortcuts. The only valid use case for unregistering
shortcuts, is for shortcuts that represent user definable actions. If the user removes such an action, shortcuts, is for shortcuts that represent user definable actions. If the user removes such an action,
......
...@@ -44,13 +44,13 @@ ...@@ -44,13 +44,13 @@
\class Core::Command \class Core::Command
\mainclass \mainclass
\brief The class Command represents an action like a menu item, tool button, or shortcut. \brief The Command class represents an action, such as a menu item, tool button, or shortcut.
You don't create Command objects directly, instead use \l{ActionManager::registerAction()} 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 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 action and its properties. If multiple actions are registered with the same ID (but
different contexts) the returned Command is the shared one between these actions. different contexts) the returned Command is the shared one between these actions.
A Command has two basic properties: A default shortcut and a default text. The default A Command has two basic properties: a default shortcut and a default text. The default
shortcut is a key sequence that the user can use to trigger the active action that shortcut is a key sequence that the user can use to trigger the active action that
the Command represents. The default text is e.g. used for representing the Command the Command represents. The default text is e.g. used for representing the Command
in the keyboard shortcut preference pane. If the default text is empty, the text in the keyboard shortcut preference pane. If the default text is empty, the text
...@@ -68,7 +68,7 @@ ...@@ -68,7 +68,7 @@
/*! /*!
\enum Command::CommandAttribute \enum Command::CommandAttribute
Defines how the user visible action is updated when the active action changes. 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 The default is to update the enabled and visible state, and to disable the
user visible action when there is no active action. user visible action when there is no active action.
\omitvalue CA_Mask \omitvalue CA_Mask
...@@ -86,7 +86,7 @@ ...@@ -86,7 +86,7 @@
/*! /*!
\fn void Command::setDefaultKeySequence(const QKeySequence &key) \fn void Command::setDefaultKeySequence(const QKeySequence &key)
Set the default keyboard shortcut that can be used to activate this command to \a key. Sets the default keyboard shortcut that can be used to activate this command to \a key.
This is used if the user didn't customize the shortcut, or resets the shortcut This is used if the user didn't customize the shortcut, or resets the shortcut
to the default one. to the default one.
*/ */
...@@ -116,10 +116,10 @@ ...@@ -116,10 +116,10 @@
/*! /*!
\fn void Command::setDescription(const QString &text) \fn void Command::setDescription(const QString &text)
Set the \a text that is used to represent the Command in the Sets the \a text that is used to represent the Command in the
keyboard shortcut settings dialog. If you don't set this, keyboard shortcut settings dialog. If you do not set this,
the current text from the user visible action is taken (which the current text from the user visible action is taken (which
is ok in many cases). is fine in many cases).
*/ */
/*! /*!
...@@ -160,7 +160,7 @@ ...@@ -160,7 +160,7 @@
/*! /*!
\fn void Command::setAttribute(CommandAttribute attribute) \fn void Command::setAttribute(CommandAttribute attribute)
Add the \a attribute to the attributes of this Command. Adds \a attribute to the attributes of this Command.
\sa CommandAttribute \sa CommandAttribute
\sa removeAttribute() \sa removeAttribute()
\sa hasAttribute() \sa hasAttribute()
...@@ -168,14 +168,14 @@ ...@@ -168,14 +168,14 @@
/*! /*!
\fn void Command::removeAttribute(CommandAttribute attribute) \fn void Command::removeAttribute(CommandAttribute attribute)
Remove the \a attribute from the attributes of this Command. Removes \a attribute from the attributes of this Command.
\sa CommandAttribute \sa CommandAttribute
\sa setAttribute() \sa setAttribute()
*/ */
/*! /*!
\fn bool Command::hasAttribute(CommandAttribute attribute) const \fn bool Command::hasAttribute(CommandAttribute attribute) const
Returns if the Command has the \a attribute set. Returns whether the Command has the \a attribute set.
\sa CommandAttribute \sa CommandAttribute
\sa removeAttribute() \sa removeAttribute()
\sa setAttribute() \sa setAttribute()
...@@ -183,19 +183,19 @@ ...@@ -183,19 +183,19 @@
/*! /*!
\fn bool Command::isActive() const \fn bool Command::isActive() const
Returns if the Command has an active action/shortcut for the current Returns whether the Command has an active action or shortcut for the current
context. context.
*/ */
/*! /*!
\fn bool Command::isScriptable() const \fn bool Command::isScriptable() const
Returns if the Command is scriptable. A scriptable command can be called Returns whether the Command is scriptable. A scriptable command can be called
from a script without the need for the user to interact with it. from a script without the need for the user to interact with it.
*/ */
/*! /*!
\fn bool Command::isScriptable(const Context &) const \fn bool Command::isScriptable(const Context &) const
Returns if the Command is scriptable for the given context. 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 A scriptable command can be called from a script without the need for the user to
interact with it. interact with it.
*/ */
......
...@@ -248,9 +248,10 @@ void BaseFileWizardParameters::setDescriptionImage(const QString &path) ...@@ -248,9 +248,10 @@ void BaseFileWizardParameters::setDescriptionImage(const QString &path)
/*! /*!
\class Core::Internal::WizardEventLoop \class Core::Internal::WizardEventLoop
\brief Special event loop that runs a QWizard and terminates if the page changes. \brief The WizardEventLoop class implements a special event
loop that runs a QWizard and terminates if the page changes.
Use by Core::BaseFileWizard to intercept the change from the standard wizard pages Used by Core::BaseFileWizard to intercept the change from the standard wizard pages
to the extension pages (as the latter require the list of Core::GeneratedFile generated). to the extension pages (as the latter require the list of Core::GeneratedFile generated).
Synopsis: Synopsis:
...@@ -345,13 +346,12 @@ void WizardEventLoop::rejected() ...@@ -345,13 +346,12 @@ void WizardEventLoop::rejected()
\brief The BaseFileWizard class implements a generic wizard for \brief The BaseFileWizard class implements a generic wizard for
creating files. creating files.
The abstract methods: The following abstract methods must be implemented:
\list \list
\li createWizardDialog(): Called to create the QWizard dialog to be shown \li createWizardDialog(): Called to create the QWizard dialog to be shown.
\li generateFiles(): Generate file content \li generateFiles(): Generates file content.
\endlist \endlist
must be implemented.
The behaviour can be further customized by overwriting the virtual method \c postGenerateFiles(), The behaviour can be further customized by overwriting the virtual method \c postGenerateFiles(),
which is called after generating the files. which is called after generating the files.
...@@ -561,21 +561,23 @@ Core::IWizard::WizardFlags BaseFileWizard::flags() const ...@@ -561,21 +561,23 @@ Core::IWizard::WizardFlags BaseFileWizard::flags() const
/*! /*!
\fn virtual QWizard *Core::BaseFileWizard::createWizardDialog(QWidget *parent, \fn virtual QWizard *Core::BaseFileWizard::createWizardDialog(QWidget *parent,
const QString &defaultPath, const WizardDialogParameters &wizardDialogParameters) const
const WizardPageList &extensionPages) const = 0
\brief Implement to create the wizard dialog on the parent, adding the extension pages. Creates the wizard dialog on the \a parent with the
\a wizardDialogParameters.
*/ */
/*! /*!
\fn virtual Core::GeneratedFiles Core::BaseFileWizard::generateFiles(const QWizard *w, \fn virtual Core::GeneratedFiles Core::BaseFileWizard::generateFiles(const QWizard *w,
QString *errorMessage) const = 0 QString *errorMessage) const = 0
\brief Overwrite to query the parameters from the dialog and generate the files. Overwrite to query the parameters from the dialog and generate the files.
Note: This does not generate physical files, but merely the list of Core::GeneratedFile. \note This does not generate physical files, but merely the list of
Core::GeneratedFile.
*/ */
/*! /*!
\brief Physically write files. Physically writes files.
Re-implement (calling the base implementation) to create files with CustomGeneratorAttribute set. Re-implement (calling the base implementation) to create files with CustomGeneratorAttribute set.
*/ */
...@@ -592,7 +594,7 @@ bool BaseFileWizard::writeFiles(const GeneratedFiles &files, QString *errorMessa ...@@ -592,7 +594,7 @@ bool BaseFileWizard::writeFiles(const GeneratedFiles &files, QString *errorMessa
} }
/*! /*!
\brief Sets some standard options on a QWizard Sets some standard options on a QWizard.
*/ */
void BaseFileWizard::setupWizard(QWizard *w) void BaseFileWizard::setupWizard(QWizard *w)
...@@ -614,8 +616,8 @@ void BaseFileWizard::setupWizard(QWizard *w) ...@@ -614,8 +616,8 @@ void BaseFileWizard::setupWizard(QWizard *w)
} }
/*! /*!
\brief Read "shortTitle" dynamic property of the pageId and apply it as the title Reads the \c shortTitle dynamic property of \a pageId and applies it as
of corresponding progress item the title of corresponding progress item.
*/ */
void BaseFileWizard::applyExtensionPageShortTitle(Utils::Wizard *wizard, int pageId) void BaseFileWizard::applyExtensionPageShortTitle(Utils::Wizard *wizard, int pageId)
...@@ -634,7 +636,7 @@ void BaseFileWizard::applyExtensionPageShortTitle(Utils::Wizard *wizard, int pag ...@@ -634,7 +636,7 @@ void BaseFileWizard::applyExtensionPageShortTitle(Utils::Wizard *wizard, int pag
} }
/*! /*!
\brief Overwrite to perform steps to be done after files are actually created. Overwrite to perform steps to be done after files are actually created.
The default implementation opens editors with the newly generated files. The default implementation opens editors with the newly generated files.
*/ */
...@@ -645,7 +647,7 @@ bool BaseFileWizard::postGenerateFiles(const QWizard *, const GeneratedFiles &l, ...@@ -645,7 +647,7 @@ bool BaseFileWizard::postGenerateFiles(const QWizard *, const GeneratedFiles &l,
} }
/*! /*!
\brief Utility to open the editors for the files whose attribute is set accordingly. Opens the editors for the files whose attribute is set accordingly.
*/ */
bool BaseFileWizard::postGenerateOpenEditors(const GeneratedFiles &l, QString *errorMessage) bool BaseFileWizard::postGenerateOpenEditors(const GeneratedFiles &l, QString *errorMessage)
...@@ -663,8 +665,8 @@ bool BaseFileWizard::postGenerateOpenEditors(const GeneratedFiles &l, QString *e ...@@ -663,8 +665,8 @@ bool BaseFileWizard::postGenerateOpenEditors(const GeneratedFiles &l, QString *e
} }
/*! /*!
\brief Utility that performs an overwrite check on a set of files. It checks if Performs an overwrite check on a set of \a files. Checks if the file exists and
the file exists, can be overwritten at all and prompts the user with a summary. can be overwritten at all, and then prompts the user with a summary.
*/ */
BaseFileWizard::OverwriteResult BaseFileWizard::promptOverwrite(GeneratedFiles *files, BaseFileWizard::OverwriteResult BaseFileWizard::promptOverwrite(GeneratedFiles *files,
...@@ -745,7 +747,8 @@ BaseFileWizard::OverwriteResult BaseFileWizard::promptOverwrite(GeneratedFiles * ...@@ -745,7 +747,8 @@ BaseFileWizard::OverwriteResult BaseFileWizard::promptOverwrite(GeneratedFiles *
} }
/*! /*!
\brief Build a file name, adding the extension unless baseName already has one. Constructs a file name, adding the \a extension unless \a baseName already has
one.
*/ */
QString BaseFileWizard::buildFileName(const QString &path, QString BaseFileWizard::buildFileName(const QString &path,
...@@ -769,7 +772,7 @@ QString BaseFileWizard::buildFileName(const QString &path, ...@@ -769,7 +772,7 @@ QString BaseFileWizard::buildFileName(const QString &path,
} }
/*! /*!
\brief Utility that returns the preferred suffix for a mime type Returns the preferred suffix for \a mimeType.
*/ */
QString BaseFileWizard::preferredSuffix(const QString &mimeType) QString BaseFileWizard::preferredSuffix(const QString &mimeType)
...@@ -797,7 +800,7 @@ QString BaseFileWizard::preferredSuffix(const QString &mimeType) ...@@ -797,7 +800,7 @@ QString BaseFileWizard::preferredSuffix(const QString &mimeType)
\fn Core::GeneratedFiles Core::StandardFileWizard::generateFilesFromPath(const QString &path, \fn Core::GeneratedFiles Core::StandardFileWizard::generateFilesFromPath(const QString &path,
const QString &name, const QString &name,
QString *errorMessage) const = 0 QString *errorMessage) const = 0
\brief Newly introduced virtual that creates the files under the path. Creates the files with the \a name under the \a path.
*/ */
StandardFileWizard::StandardFileWizard(const BaseFileWizardParameters &parameters, StandardFileWizard::StandardFileWizard(const BaseFileWizardParameters &parameters,
...@@ -807,7 +810,7 @@ StandardFileWizard::StandardFileWizard(const BaseFileWizardParameters &parameter ...@@ -807,7 +810,7 @@ StandardFileWizard::StandardFileWizard(const BaseFileWizardParameters &parameter
} }
/*! /*!
\brief Implemented to create a Utils::FileWizardDialog. Creates a Utils::FileWizardDialog.
*/ */
QWizard *StandardFileWizard::createWizardDialog(QWidget *parent, QWizard *StandardFileWizard::createWizardDialog(QWidget *parent,
...@@ -825,7 +828,7 @@ QWizard *StandardFileWizard::createWizardDialog(QWidget *parent, ...@@ -825,7 +828,7 @@ QWizard *StandardFileWizard::createWizardDialog(QWidget *parent,
} }
/*! /*!
\brief Implemented to retrieve path and name and call generateFilesFromPath() Retrieves \a path and \a fileName and calls \c generateFilesFromPath().
*/ */
GeneratedFiles StandardFileWizard::generateFiles(const QWizard *w, GeneratedFiles StandardFileWizard::generateFiles(const QWizard *w,
......
...@@ -39,15 +39,16 @@ ...@@ -39,15 +39,16 @@
into the plugin manager object pool (e.g. ExtensionSystem::PluginManager::addObject). into the plugin manager object pool (e.g. ExtensionSystem::PluginManager::addObject).
Guidelines for implementing: Guidelines for implementing:
\list \list
\li id() is a unique identifier for referencing this page \li \c id() is a unique identifier for referencing this page
\li displayName() is the (translated) name for display \li \c displayName() is the (translated) name for display
\li category() is the unique id for the category that the page should be displayed in \li \c category() is the unique id for the category that the page should be displayed in
\li displayCategory() is the translated name of the category \li \c displayCategory() is the translated name of the category
\li createPage() is called to retrieve the widget to show in the preferences dialog \li \c createPage() is called to retrieve the widget to show in the
\gui Options dialog
The widget will be destroyed by the widget hierarchy when the dialog closes The widget will be destroyed by the widget hierarchy when the dialog closes
\li apply() is called to store the settings. It should detect if any changes have been \li \c apply() is called to store the settings. It should detect if any changes have been
made and store those made and store those
\li finish() is called directly before the preferences dialog closes \li \c finish() is called directly before the \gui Options dialog closes
\li matches() is used for the options dialog search filter \li \c matches() is used for the \gui Options dialog search filter
\endlist \endlist
*/ */
...@@ -158,7 +158,7 @@ ReadOnlyFilesDialog::~ReadOnlyFilesDialog() ...@@ -158,7 +158,7 @@ ReadOnlyFilesDialog::~ReadOnlyFilesDialog()
} }
/*! /*!
* \brief Set a user defined message in the dialog. * Sets a user defined message in the dialog.
* \internal * \internal
*/ */
void ReadOnlyFilesDialog::setMessage(const QString &message) void ReadOnlyFilesDialog::setMessage(const QString &message)
...@@ -167,8 +167,8 @@ void ReadOnlyFilesDialog::setMessage(const QString &message) ...@@ -167,8 +167,8 @@ void ReadOnlyFilesDialog::setMessage(const QString &message)
} }
/*! /*!
* \brief Enable the error output to the user via a messageBox. * Enables the error output to the user via a message box. \a warning should
* \param warning Added to the dialog, should show possible consequences if the file is still read only. * show the possible consequences if the file is still read only.
* \internal * \internal
*/ */
void ReadOnlyFilesDialog::setShowFailWarning(bool show, const QString &warning) void ReadOnlyFilesDialog::setShowFailWarning(bool show, const QString &warning)
...@@ -178,7 +178,7 @@ void ReadOnlyFilesDialog::setShowFailWarning(bool show, const QString &warning) ...@@ -178,7 +178,7 @@ void ReadOnlyFilesDialog::setShowFailWarning(bool show, const QString &warning)
} }
/*! /*!
* \brief Opens a message box with an error description according to the type. * Opens a message box with an error description according to the type.
* \internal * \internal
*/ */
void ReadOnlyFilesDialog::promptFailWarning(const QStringList &files, ReadOnlyResult type) const void ReadOnlyFilesDialog::promptFailWarning(const QStringList &files, ReadOnlyResult type) const
...@@ -237,12 +237,13 @@ void ReadOnlyFilesDialog::promptFailWarning(const QStringList &files, ReadOnlyRe ...@@ -237,12 +237,13 @@ void ReadOnlyFilesDialog::promptFailWarning(const QStringList &files, ReadOnlyRe
} }
/*! /*!
* \brief Executes the dialog. * Executes the ReadOnlyFilesDialog dialog.
* \return ReadOnlyResult which gives information about the operation which was used to make the files writable. * Returns ReadOnlyResult to provide information about the operation that was
* used to make the files writable.
* \internal * \internal
* *
* Also displays an error dialog when some operations can't be executed and the function * Also displays an error dialog when some operations cannot be executed and the
* setShowFailWarning was called. * function \c setShowFailWarning() was called.
*/ */
int ReadOnlyFilesDialog::exec() int ReadOnlyFilesDialog::exec()
{ {
...@@ -287,9 +288,9 @@ int ReadOnlyFilesDialog::exec() ...@@ -287,9 +288,9 @@ int ReadOnlyFilesDialog::exec()
} }
/*! /*!
* \brief Creates a radio button in the column specified with type. * Creates a radio button in the group \a group and in the column specified by
* \param group the created button will be added to this group. * \a type.
* \return the created button. * Returns the created button.
* \internal * \internal
*/ */
QRadioButton* ReadOnlyFilesDialog::createRadioButtonForItem(QTreeWidgetItem *item, QButtonGroup *group, QRadioButton* ReadOnlyFilesDialog::createRadioButtonForItem(QTreeWidgetItem *item, QButtonGroup *group,
...@@ -304,7 +305,8 @@ QRadioButton* ReadOnlyFilesDialog::createRadioButtonForItem(QTreeWidgetItem *ite ...@@ -304,7 +305,8 @@ QRadioButton* ReadOnlyFilesDialog::createRadioButtonForItem(QTreeWidgetItem *ite
} }
/*! /*!
* \brief Checks the type of the select all combo box and change the user selection per file accordingly. * Checks the type of the select all combo box and changes the user selection
* per file accordingly.
* \internal * \internal
*/ */
void ReadOnlyFilesDialog::setAll(int index) void ReadOnlyFilesDialog::setAll(int index)
...@@ -331,7 +333,8 @@ void ReadOnlyFilesDialog::setAll(int index) ...@@ -331,7 +333,8 @@ void ReadOnlyFilesDialog::setAll(int index)
} }
/*! /*!
* \brief Updates the select all combo box depending on the selection in the tree widget the user made. * Updates the select all combo box depending on the selection the user made in
* the tree widget.
* \internal * \internal
*/ */
void ReadOnlyFilesDialog::updateSelectAll()