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()
}
/*!
\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
or to add menu items to the menu. The ActionManager owns
......@@ -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
or to add menus to the menu bar. The ActionManager owns
......@@ -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
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
}
/*!
\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
owned by the ActionManager. You can registered several shortcuts with the
......@@ -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.
\sa ActionManager::registerAction()
......@@ -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.
\sa ActionManager::createMenu()
......@@ -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()
{
......@@ -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
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)
}
/*!
\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
shortcuts, is for shortcuts that represent user definable actions. If the user removes such an action,
......
......@@ -44,13 +44,13 @@
\class Core::Command
\mainclass
\brief The class Command represents an action like a menu item, tool button, or shortcut.
You don't create Command objects directly, instead use \l{ActionManager::registerAction()}
\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
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
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
......@@ -68,7 +68,7 @@
/*!
\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
user visible action when there is no active action.
\omitvalue CA_Mask
......@@ -86,7 +86,7 @@
/*!
\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
to the default one.
*/
......@@ -116,10 +116,10 @@
/*!
\fn void Command::setDescription(const QString &text)
Set the \a text that is used to represent the Command in the
keyboard shortcut settings dialog. If you don't set this,
Sets the \a text that is used to represent the Command in the
keyboard shortcut settings dialog. If you do not set this,
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 @@
/*!
\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 removeAttribute()
\sa hasAttribute()
......@@ -168,14 +168,14 @@
/*!
\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 setAttribute()
*/
/*!
\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 removeAttribute()
\sa setAttribute()
......@@ -183,19 +183,19 @@
/*!
\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.
*/
/*!
\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.
*/
/*!
\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
interact with it.
*/
......
......@@ -248,9 +248,10 @@ void BaseFileWizardParameters::setDescriptionImage(const QString &path)
/*!
\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).
Synopsis:
......@@ -345,13 +346,12 @@ void WizardEventLoop::rejected()
\brief The BaseFileWizard class implements a generic wizard for
creating files.
The abstract methods:
The following abstract methods must be implemented:
\list
\li createWizardDialog(): Called to create the QWizard dialog to be shown
\li generateFiles(): Generate file content
\li createWizardDialog(): Called to create the QWizard dialog to be shown.
\li generateFiles(): Generates file content.
\endlist
must be implemented.
The behaviour can be further customized by overwriting the virtual method \c postGenerateFiles(),
which is called after generating the files.
......@@ -561,21 +561,23 @@ Core::IWizard::WizardFlags BaseFileWizard::flags() const
/*!
\fn virtual QWizard *Core::BaseFileWizard::createWizardDialog(QWidget *parent,
const QString &defaultPath,
const WizardPageList &extensionPages) const = 0
\brief Implement to create the wizard dialog on the parent, adding the extension pages.
const WizardDialogParameters &wizardDialogParameters) const
Creates the wizard dialog on the \a parent with the
\a wizardDialogParameters.
*/
/*!
\fn virtual Core::GeneratedFiles Core::BaseFileWizard::generateFiles(const QWizard *w,
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.
*/
......@@ -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)
......@@ -614,8 +616,8 @@ void BaseFileWizard::setupWizard(QWizard *w)
}
/*!
\brief Read "shortTitle" dynamic property of the pageId and apply it as the title
of corresponding progress item
Reads the \c shortTitle dynamic property of \a pageId and applies it as
the title of corresponding progress item.
*/
void BaseFileWizard::applyExtensionPageShortTitle(Utils::Wizard *wizard, int pageId)
......@@ -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.
*/
......@@ -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)
......@@ -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
the file exists, can be overwritten at all and prompts the user with a summary.
Performs an overwrite check on a set of \a files. Checks if the file exists and
can be overwritten at all, and then prompts the user with a summary.
*/
BaseFileWizard::OverwriteResult BaseFileWizard::promptOverwrite(GeneratedFiles *files,
......@@ -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,
......@@ -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)
......@@ -797,7 +800,7 @@ QString BaseFileWizard::preferredSuffix(const QString &mimeType)
\fn Core::GeneratedFiles Core::StandardFileWizard::generateFilesFromPath(const QString &path,
const QString &name,
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,
......@@ -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,
......@@ -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,
......
......@@ -39,15 +39,16 @@
into the plugin manager object pool (e.g. ExtensionSystem::PluginManager::addObject).
Guidelines for implementing:
\list
\li id() is a unique identifier for referencing this page
\li displayName() is the (translated) name for display
\li 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 createPage() is called to retrieve the widget to show in the preferences dialog
\li \c id() is a unique identifier for referencing this page
\li \c displayName() is the (translated) name for display
\li \c category() is the unique id for the category that the page should be displayed in
\li \c displayCategory() is the translated name of the category
\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
\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
\li finish() is called directly before the preferences dialog closes
\li matches() is used for the options dialog search filter
\li \c finish() is called directly before the \gui Options dialog closes
\li \c matches() is used for the \gui Options dialog search filter
\endlist
*/
......@@ -158,7 +158,7 @@ ReadOnlyFilesDialog::~ReadOnlyFilesDialog()
}
/*!
* \brief Set a user defined message in the dialog.
* Sets a user defined message in the dialog.
* \internal
*/
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.
* \param warning Added to the dialog, should show possible consequences if the file is still read only.
* Enables the error output to the user via a message box. \a warning should
* show the possible consequences if the file is still read only.
* \internal
*/
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
*/
void ReadOnlyFilesDialog::promptFailWarning(const QStringList &files, ReadOnlyResult type) const
......@@ -237,12 +237,13 @@ void ReadOnlyFilesDialog::promptFailWarning(const QStringList &files, ReadOnlyRe
}
/*!
* \brief Executes the dialog.
* \return ReadOnlyResult which gives information about the operation which was used to make the files writable.
* Executes the ReadOnlyFilesDialog dialog.
* Returns ReadOnlyResult to provide information about the operation that was
* used to make the files writable.
* \internal
*
* Also displays an error dialog when some operations can't be executed and the function
* setShowFailWarning was called.
* Also displays an error dialog when some operations cannot be executed and the
* function \c setShowFailWarning() was called.
*/
int ReadOnlyFilesDialog::exec()
{
......@@ -287,9 +288,9 @@ int ReadOnlyFilesDialog::exec()
}
/*!
* \brief Creates a radio button in the column specified with type.
* \param group the created button will be added to this group.
* \return the created button.
* Creates a radio button in the group \a group and in the column specified by
* \a type.
* Returns the created button.
* \internal
*/
QRadioButton* ReadOnlyFilesDialog::createRadioButtonForItem(QTreeWidgetItem *item, QButtonGroup *group,
......@@ -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
*/
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
*/
void ReadOnlyFilesDialog::updateSelectAll()
......@@ -349,8 +352,10 @@ void ReadOnlyFilesDialog::updateSelectAll()
}
/*!
* \brief Adds files to the dialog and check for possible operation to make the file writable.
* \param fileNames A List of files which should be added to the dialog.
* Adds files to the dialog and checks for a possible operation to make the file
* writable.
* \a fileNames contains the list of the files that should be added to the
* dialog.
* \internal
*/
void ReadOnlyFilesDialog::initDialog(const QStringList &fileNames)
......
......@@ -66,27 +66,29 @@
\inheaderfile documentmanager.h
\brief The DocumentManager class manages a set of IDocument objects.
The DocumentManager service monitors a set of IDocument's. Plugins should register
files they work with at the service. The files the IDocument's point to will be
monitored at filesystem level. If a file changes, the status of the IDocument's
The DocumentManager service monitors a set of IDocument objects. Plugins
should register files they work with at the service. The files the IDocument
objects point to will be monitored at filesystem level. If a file changes,
the status of the IDocument object
will be adjusted accordingly. Furthermore, on application exit the user will
be asked to save all modified files.
Different IDocument objects in the set can point to the same file in the
filesystem. The monitoring for a IDocument can be blocked by blockFileChange(), and
enabled again by unblockFileChange().
filesystem. The monitoring for an IDocument can be blocked by
\c blockFileChange(), and enabled again by \c unblockFileChange().
The functions expectFileChange() and unexpectFileChange() mark a file change
The functions \c expectFileChange() and \c unexpectFileChange() mark a file change
as expected. On expected file changes all IDocument objects are notified to reload
themselves.
The DocumentManager service also provides two convenience methods for saving
files: saveModifiedFiles() and saveModifiedFilesSilently(). Both take a list
files: \c saveModifiedFiles() and \c saveModifiedFilesSilently(). Both take a list
of FileInterfaces as an argument, and return the list of files which were
_not_ saved.
The service also manages the list of recent files to be shown to the user
(see addToRecentFiles() and recentFiles()).
The service also manages the list of recent files to be shown to the user.
\sa addToRecentFiles(), recentFiles()
*/
static const char settingsGroupC[] = "RecentFiles";
......@@ -156,7 +158,7 @@ struct DocumentManagerPrivate
QString m_projectsDirectory;
bool m_useProjectsDirectory;
QString m_buildDirectory;
// When we are callling into a IDocument
// When we are calling into an IDocument
// we don't want to receive a changed()
// signal
// That makes the code easier
......@@ -359,12 +361,13 @@ static void dump()
*/
/*!
\brief Tells the file manager that a file has been renamed on disk from within Qt Creator.
Tells the file manager that a file has been renamed on disk from within \QC.
Needs to be called right after the actual renaming on disk (i.e. before the file system
Needs to be called right after the actual renaming on disk (that is, before
the file system
watcher can report the event during the next event loop run). \a from needs to be an absolute file path.
This will notify all IDocument objects pointing to that file of the rename
by calling IDocument::rename, and update the cached time and permission
by calling \c IDocument::rename(), and update the cached time and permission
information to avoid annoying the user with "file has been removed"
popups.
*/
......@@ -402,7 +405,8 @@ void DocumentManager::fileNameChanged(const QString &oldName, const QString &new
}
/*!
Adds a IDocument object to the collection. If \a addWatcher is true (the default),
Adds an IDocument object to the collection. If \a addWatcher is \c true
(the default),
the file is added to a file system watcher that notifies the file manager
about file changes.
*/
......@@ -420,9 +424,10 @@ void DocumentManager::documentDestroyed(QObject *obj)
}
/*!
Removes a IDocument object from the collection.
Removes an IDocument object from the collection.
Returns true if the file specified by \a document had the addWatcher argument to addDocument() set.
Returns \c true if the file specified by \a document had the \a addWatcher
argument to \a addDocument() set.
*/
bool DocumentManager::removeDocument(IDocument *document)
{
......@@ -481,7 +486,7 @@ QString DocumentManager::fixFileName(const QString &fileName, FixMode fixmode)
}
/*!
Returns the list of IDocument's that have been modified.
Returns the list of IDocuments that have been modified.
*/
QList<IDocument *> DocumentManager::modifiedDocuments()
{
......@@ -501,7 +506,7 @@ QList<IDocument *> DocumentManager::modifiedDocuments()
}
/*!
Any subsequent change to \a fileName is treated as a expected file change.
Any subsequent change to \a fileName is treated as an expected file change.
\see DocumentManager::unexpectFileChange(const QString &fileName)
*/
......@@ -525,7 +530,7 @@ static void updateExpectedState(const QString &fileName)
}
/*!
Any change to \a fileName are unexpected again.
Any changes to \a fileName are unexpected again.
\see DocumentManager::expectFileChange(const QString &fileName)
*/
......@@ -550,7 +555,8 @@ void DocumentManager::unexpectFileChange(const QString &fileName)
/*!
Tries to save the files listed in \a documents. The \a cancelled argument is set to true
if the user cancelled the dialog. Returns the files that could not be saved. If the files
listed in documents have no write permissions an additional dialog will be prompted to
listed in documents have no write permissions, an additional dialog will be
displayed to
query the user for these permissions.
*/
QList<IDocument *> DocumentManager::saveModifiedDocumentsSilently(const QList<IDocument *> &documents, bool *cancelled)
......@@ -559,14 +565,17 @@ QList<IDocument *> DocumentManager::saveModifiedDocumentsSilently(const QList<ID
}
/*!
Asks the user whether to save the files listed in \a documents .
Opens a dialog with the given \a message, and a additional
text that should be used to ask if the user wants to enabled automatic save
Asks the user whether to save the files listed in \a documents. Opens a
dialog that displays the \a message, and additional text to ask the users
if they want to enable automatic saving
of modified files (in this context).
The \a cancelled argument is set to true if the user cancelled the dialog,
\a alwaysSave is set to match the selection of the user, if files should
The \a cancelled argument is set to true if the user cancels the dialog.
\a alwaysSave is set to match the selection of the user if files should
always automatically be saved. If the files listed in documents have no write
permissions an additional dialog will be prompted to query the user for these permissions.
permissions, an additional dialog will be displayed to query the user for
these permissions.
Returns the files that have not been saved.
*/
QList<IDocument *> DocumentManager::saveModifiedDocuments(const QList<IDocument *> &documents,
......@@ -740,7 +749,7 @@ QString DocumentManager::getSaveFileNameWithExtension(const QString &title, cons
}
/*!
Asks the user for a new file name (Save File As) for /arg document.
Asks the user for a new file name (\gui {Save File As}) for \a document.
*/
QString DocumentManager::getSaveAsFileName(const IDocument *document, const QString &filter, QString *selectedFilter)
{
......@@ -775,9 +784,9 @@ QString DocumentManager::getSaveAsFileName(const IDocument *document, const QStr
/*!
Asks the user for a set of file names to be opened. The \a filters
and \a selectedFilter parameters is interpreted like in
QFileDialog::getOpenFileNames(), \a pathIn specifies a path to open the dialog
in, if that is not overridden by the users policy.
and \a selectedFilter arguments are interpreted like in
\c QFileDialog::getOpenFileNames(). \a pathIn specifies a path to open the
dialog in if that is not overridden by the user's policy.
*/
QStringList DocumentManager::getOpenFileNames(const QString &filters,
......@@ -1047,8 +1056,8 @@ void DocumentManager::syncWithEditor(const QList<Core::IContext *> &context)
/*!
Adds the \a fileName to the list of recent files. Associates the file to
be reopened with an editor of the given \a editorId, if possible.
\a editorId defaults to the empty id, which means to let the system figure out
be reopened with the editor that has the specified \a editorId, if possible.
\a editorId defaults to the empty id, which lets \QC figure out
the best editor itself.
*/
void DocumentManager::addToRecentFiles(const QString &fileName, const Id &editorId)
......@@ -1070,7 +1079,7 @@ void DocumentManager::addToRecentFiles(const QString &fileName, const Id &editor
/*!
Clears the list of recent files. Should only be called by
the core plugin when the user chooses to clear it.
the core plugin when the user chooses to clear the list.
*/
void DocumentManager::clearRecentFiles()
{
......@@ -1147,8 +1156,8 @@ void readSettings()
/*!
The current file is e.g. the file currently opened when an editor is active,
or the selected file in case a Project Explorer is active ...
The current file is the file currently opened when an editor is active,
or the selected file in case a Project Explorer is active.