feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

Doc: Fix QDoc warnings in Core plugin Wizard classes

Browse Source 
Task-number: QTCREATORBUG-23620
Change-Id: Ia8d27be35911378703126c1e2d06a157ce6185f0
Reviewed-by: Eike Ziller <eike.ziller@qt.io>
This commit is contained in:
Leena Miettinen
2020-02-20 13:14:01 +01:00
parent ea7d59e58a
commit 45a575c218
3 changed files with 105 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
doc/qtcreatordev/src/common-extension-tasks.qdoc
View File

@@ -60,11 +60,16 @@
\row
\li Add a new wizard.
\li You can extend the wizards in File > New File or Project with
your own file and project templates.
\li \l{Core::IWizard}, \l{Core::StandardFileWizard},
\l{Core::BaseFileWizard}, \l{Core::BaseFileWizardParameters}
\li You can extend the wizards in \uicontrol File >
\uicontrol {New File or Project} with your own file
and project templates. We recommend that you create
JSON-based wizards instead of implementing new
wizards in C++ code.
\li \l{https://doc.qt.io/qtcreator/creator-project-wizards.html}
{Adding New Custom Wizards}
\l{Core::IWizardFactory}, \l{Core::BaseFileWizardFactory},
\l{Core::BaseFileWizard}, \l{Core::WizardDialogParameters}
\row
\li Add support for a new version control system.
\li Version control systems integrated in \QC are Bazaar, CVS, Git,

95
src/plugins/coreplugin/basefilewizardfactory.cpp
View File

@@ -58,20 +58,11 @@ static int indexOfFile(const GeneratedFiles &f, const QString &path)
/*!
\class Core::BaseFileWizard
\brief The BaseFileWizard class implements a generic wizard for
\inmodule QtCreator
\brief The BaseFileWizard class implements a is a convenience class for
creating files.
The following abstract functions must be implemented:
\list
\li create(): Called to create the QWizard dialog to be shown.
\li generateFiles(): Generates file content.
\endlist
The behaviour can be further customized by overwriting the virtual function \c postGenerateFiles(),
which is called after generating the files.
\sa Core::GeneratedFile, Core::BaseFileWizardParameters, Core::StandardFileWizard
\sa Core::Internal::WizardEventLoop
\sa Core::BaseFileWizardFactory
*/
Utils::Wizard *BaseFileWizardFactory::runWizardImpl(const QString &path, QWidget *parent,
@@ -98,25 +89,54 @@ Utils::Wizard *BaseFileWizardFactory::runWizardImpl(const QString &path, QWidget
}
/*!
\fn virtual QWizard *Core::BaseFileWizard::create(QWidget *parent,
const WizardDialogParameters &parameters) const
\class Core::BaseFileWizardFactory
\inmodule QtCreator
\brief The BaseFileWizardFactory class implements a generic wizard for
creating files.
The following abstract functions must be implemented:
\list
\li create(): Called to create the QWizard dialog to be shown.
\li generateFiles(): Generates file content.
\endlist
The behavior can be further customized by overwriting the virtual function
postGenerateFiles(), which is called after generating the files.
\note Instead of using this class, we recommend that you create JSON-based
wizards, as instructed in \l{https://doc.qt.io/qtcreator/creator-project-wizards.html}
{Adding New Custom Wizards}.
\sa Core::GeneratedFile, Core::WizardDialogParameters, Core::BaseFileWizard
*/
/*!
\fn Core::BaseFileWizard *Core::BaseFileWizardFactory::create(QWidget *parent,
const Core::WizardDialogParameters &parameters) const
Creates the wizard on the \a parent with the \a parameters.
*/
/*!
\fn virtual Core::GeneratedFiles Core::BaseFileWizard::generateFiles(const QWizard *w,
QString *errorMessage) const = 0
Overwrite to query the parameters from the dialog and generate the files.
\fn virtual Core::GeneratedFiles Core::BaseFileWizardFactory::generateFiles(const QWizard *w,
QString *errorMessage) const
Overwrite to query the parameters from the wizard \a w and generate the
files.
Possible errors are held in \a errorMessage.
\note This does not generate physical files, but merely the list of
Core::GeneratedFile.
*/
/*!
Physically writes files.
Physically writes \a files.
Re-implement (calling the base implementation) to create files with CustomGeneratorAttribute set.
If the files cannot be written, returns \c false and sets \a errorMessage
to the message that is displayed to users.
Re-implement (calling the base implementation) to create files with
GeneratedFile::CustomGeneratorAttribute set.
*/
bool BaseFileWizardFactory::writeFiles(const GeneratedFiles &files, QString *errorMessage) const
@@ -131,9 +151,13 @@ bool BaseFileWizardFactory::writeFiles(const GeneratedFiles &files, QString *err
}
/*!
Overwrite to perform steps to be done after files are actually created.
Overwrite to perform steps to be done by the wizard \a w after the files
specified by \a l are actually created.
The default implementation opens editors with the newly generated files.
The default implementation opens editors with the newly generated files
that have GeneratedFile::OpenEditorAttribute set.
Returns \a errorMessage if errors occur.
*/
bool BaseFileWizardFactory::postGenerateFiles(const QWizard *, const GeneratedFiles &l,
@@ -143,7 +167,12 @@ bool BaseFileWizardFactory::postGenerateFiles(const QWizard *, const GeneratedFi
}
/*!
Opens the editors for the files whose attribute is set accordingly.
Opens the editors for the files \a l if their
GeneratedFile::OpenEditorAttribute attribute
is set accordingly.
If the editorrs cannot be opened, returns \c false and dand sets
\a errorMessage to the message that is displayed to users.
*/
bool BaseFileWizardFactory::postGenerateOpenEditors(const GeneratedFiles &l, QString *errorMessage)
@@ -163,6 +192,8 @@ bool BaseFileWizardFactory::postGenerateOpenEditors(const GeneratedFiles &l, QSt
/*!
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.
Returns \a errorMessage if the file cannot be overwritten.
*/
BaseFileWizardFactory::OverwriteResult BaseFileWizardFactory::promptOverwrite(GeneratedFiles *files,
@@ -243,8 +274,8 @@ BaseFileWizardFactory::OverwriteResult BaseFileWizardFactory::promptOverwrite(Ge
}
/*!
Constructs a file name, adding the \a extension unless \a baseName already has
one.
Constructs a file name including \a path, adding the \a extension unless
\a baseName already has one.
*/
QString BaseFileWizardFactory::buildFileName(const QString &path,
@@ -285,14 +316,18 @@ QString BaseFileWizardFactory::preferredSuffix(const QString &mimeType)
}
/*!
\class Core::StandardFileWizard
\brief The StandardFileWizard class is a convenience class for
creating one file.
\class Core::WizardDialogParameters
\inmodule QtCreator
\brief The WizardDialogParameters class holds parameters for the new file
wizard dialog.
It uses Utils::FileWizardDialog and introduces a new virtual to generate the
files from path and name.
\sa Core::GeneratedFile, Core::BaseFileWizardFactory
*/
\sa Core::GeneratedFile, Core::BaseFileWizardParameters, Core::BaseFileWizard
/*!
\enum Core::WizardDialogParameters::DialogParameterEnum
This enum type holds whether to force capital letters for file names.
\value ForceCapitalLetterForFileName Forces capital letters for file names.
*/
} // namespace Core

74
src/plugins/coreplugin/iwizardfactory.cpp
View File

@@ -41,18 +41,23 @@
/*!
\class Core::IWizardFactory
\mainclass
\inmodule QtCreator
\ingroup mainclasses
\brief The class IWizardFactory is the base class for all wizard factories
(for example shown in \gui {File | New}).
\brief The IWizardFactory class is the base class for all wizard factories.
The wizard interface is a very thin abstraction for the \gui{New...} wizards.
Basically it defines what to show to the user in the wizard selection dialogs,
\note Instead of using this class, we recommend that you create JSON-based
wizards, as instructed in \l{https://doc.qt.io/qtcreator/creator-project-wizards.html}
{Adding New Custom Wizards}.
The wizard interface is a very thin abstraction for the wizards in
\uicontrol File > \uicontrol {New File or Project}.
Basically, it defines what to show to the user in the wizard selection dialogs,
and a hook that is called if the user selects the wizard.
Wizards can then perform any operations they like, including showing dialogs and
creating files. Often it is not necessary to create your own wizard from scratch,
instead use one of the predefined wizards and adapt it to your needs.
creating files. Often it is not necessary to create your own wizard from scratch.
Use one of the predefined wizards and adapt it to your needs.
To make your wizard known to the system, add your IWizardFactory instance to the
plugin manager's object pool in your plugin's initialize function:
@@ -64,86 +69,60 @@
// ... do more setup
}
\endcode
\sa Core::BaseFileWizard
\sa Core::StandardFileWizard
\sa Core::BaseFileWizardFactory, Core::BaseFileWizard
*/
/*!
\enum Core::IWizardFactory::WizardKind
Used to specify what kind of objects the wizard creates. This information is used
to show e.g. only wizards that create projects when selecting a \gui{New Project}
to show e.g. only wizards that create projects when selecting a \uicontrol{New Project}
menu item.
\value FileWizard
The wizard creates one or more files.
\value ClassWizard
The wizard creates a new class (e.g. source+header files).
\value ProjectWizard
The wizard creates a new project.
*/
/*!
\fn IWizardFactory::IWizardFactory(QObject *parent)
\internal
*/
/*!
\fn IWizardFactory::~IWizardFactory()
\internal
*/
/*!
\fn Kind IWizardFactory::kind() const
\fn Core::IWizardFactory::WizardKind Core::IWizardFactory::kind() const
Returns what kind of objects are created by the wizard.
\sa Kind
*/
/*!
\fn QIcon IWizardFactory::icon() const
\fn QIcon Core::IWizardFactory::icon() const
Returns an icon to show in the wizard selection dialog.
*/
/*!
\fn QString IWizardFactory::description() const
\fn QString Core::IWizardFactory::description() const
Returns a translated description to show when this wizard is selected
in the dialog.
*/
/*!
\fn QString IWizardFactory::displayName() const
\fn QString Core::IWizardFactory::displayName() const
Returns the translated name of the wizard, how it should appear in the
dialog.
*/
/*!
\fn QString IWizardFactory::id() const
\fn QString Core::IWizardFactory::id() const
Returns an arbitrary id that is used for sorting within the category.
*/
/*!
\fn QString IWizardFactory::category() const
\fn QString Core::IWizardFactory::category() const
Returns a category ID to add the wizard to.
*/
/*!
\fn QString IWizardFactory::displayCategory() const
\fn QString Core::IWizardFactory::displayCategory() const
Returns the translated string of the category, how it should appear
in the dialog.
*/
/*!
\fn void IWizardFactory::runWizard(const QString &path,
QWidget *parent,
const QString &platform,
const QVariantMap &variables)
This function is executed when the wizard has been selected by the user
for execution. Any dialogs the wizard opens should use the given \a parent.
The \a path argument is a suggestion for the location where files should be
created. The wizard should fill this in its path selection elements as a
default path.
*/
using namespace Core;
@@ -268,6 +247,15 @@ QString IWizardFactory::runPath(const QString &defaultPath)
return path;
}
/*!
Creates the wizard that the user selected for execution on the operating
system \a platform with \a variables.
Any dialogs the wizard opens should use the given \a parent.
The \a path argument is a suggestion for the location where files should be
created. The wizard should fill this in its path selection elements as a
default path.
*/
Utils::Wizard *IWizardFactory::runWizard(const QString &path, QWidget *parent, Id platform, const QVariantMap &variables)
{
QTC_ASSERT(!s_isWizardRunning, return nullptr);