From d15da2c0f975e72db747b1f5d2f6db489b9d8ff1 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Fri, 26 May 2023 13:57:46 +0200 Subject: [PATCH] Doc: Fix qdoc warnings in Core plugin docs Change-Id: Id7b7c1c66e75ad5bce2ea9801493eb7872121e52 Reviewed-by: Eike Ziller --- .../coreplugin/actionmanager/commandbutton.cpp | 6 ++++-- .../coreplugin/dialogs/ioptionspage.cpp | 2 +- src/plugins/coreplugin/documentmanager.cpp | 4 ++++ .../coreplugin/editormanager/editormanager.cpp | 10 +++++++++- src/plugins/coreplugin/featureprovider.cpp | 12 ++++++++---- .../coreplugin/find/searchresultwindow.cpp | 3 ++- src/plugins/coreplugin/iwizardfactory.cpp | 14 ++++++++++++++ .../coreplugin/locator/ilocatorfilter.cpp | 5 ++--- src/plugins/coreplugin/session.cpp | 18 ++++++++++++++---- 9 files changed, 58 insertions(+), 16 deletions(-) diff --git a/src/plugins/coreplugin/actionmanager/commandbutton.cpp b/src/plugins/coreplugin/actionmanager/commandbutton.cpp index ed724e42d02..a8dab391368 100644 --- a/src/plugins/coreplugin/actionmanager/commandbutton.cpp +++ b/src/plugins/coreplugin/actionmanager/commandbutton.cpp @@ -92,7 +92,8 @@ QString CommandAction::toolTipBase() const } /*! - Sets the base tool tip that is extended with the command's shortcut. + Sets the base tool tip that is extended with the command's shortcut to + \a toolTipBase. \sa toolTipBase() */ @@ -155,7 +156,8 @@ QString CommandButton::toolTipBase() const } /*! - Sets the base tool tip that is extended with the command's shortcut. + Sets the base tool tip that is extended with the command's shortcut to + \a toolTipBase. \sa toolTipBase() */ diff --git a/src/plugins/coreplugin/dialogs/ioptionspage.cpp b/src/plugins/coreplugin/dialogs/ioptionspage.cpp index d7646749c68..1912045af53 100644 --- a/src/plugins/coreplugin/dialogs/ioptionspage.cpp +++ b/src/plugins/coreplugin/dialogs/ioptionspage.cpp @@ -250,7 +250,7 @@ void IOptionsPage::setLayouter(const std::function &la static QList g_optionsPages; /*! - Constructs an options page with the given \a parent and registers it + Constructs an options page and registers it at the global options page pool if \a registerGlobally is \c true. */ IOptionsPage::IOptionsPage(bool registerGlobally) diff --git a/src/plugins/coreplugin/documentmanager.cpp b/src/plugins/coreplugin/documentmanager.cpp index 226564fa0ba..98ab6514119 100644 --- a/src/plugins/coreplugin/documentmanager.cpp +++ b/src/plugins/coreplugin/documentmanager.cpp @@ -1027,6 +1027,10 @@ void DocumentManager::showFilePropertiesDialog(const FilePath &filePath) and \a selectedFilter arguments are interpreted like in QFileDialog::getOpenFileNames(). \a pathIn specifies a path to open the dialog in if that is not overridden by the user's policy. + + The \a options argument holds various options about how to run the dialog. + See the QFileDialog::Option enum for more information about the flags you + can pass. */ FilePaths DocumentManager::getOpenFileNames(const QString &filters, diff --git a/src/plugins/coreplugin/editormanager/editormanager.cpp b/src/plugins/coreplugin/editormanager/editormanager.cpp index 227ffba28c8..e7147e94cea 100644 --- a/src/plugins/coreplugin/editormanager/editormanager.cpp +++ b/src/plugins/coreplugin/editormanager/editormanager.cpp @@ -239,6 +239,10 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *) \value SwitchSplitIfAlreadyVisible Switches to another split if the document is already visible there. + \value DoNotRaise + Prevents raising the \QC window to the foreground. + \value AllowExternalEditor + Allows opening the file in an external editor. */ /*! @@ -3246,7 +3250,11 @@ void EditorManager::addCloseEditorListener(const std::function /*! Asks the user for a list of files to open and returns the choice. - \sa DocumentManager::getOpenFileNames() + The \a options argument holds various options about how to run the dialog. + See the QFileDialog::Options enum for more information about the flags you + can pass. + + \sa DocumentManager::getOpenFileNames(), QFileDialog::Options */ FilePaths EditorManager::getOpenFilePaths(QFileDialog::Options options) { diff --git a/src/plugins/coreplugin/featureprovider.cpp b/src/plugins/coreplugin/featureprovider.cpp index efe792bfb21..739bdb7067d 100644 --- a/src/plugins/coreplugin/featureprovider.cpp +++ b/src/plugins/coreplugin/featureprovider.cpp @@ -13,18 +13,22 @@ for wizards. The features provided by an object in the object pool implementing IFeatureProvider - will be respected by wizards implementing IWizard. + will be respected by wizards implementing IWizardFactory. This feature set, provided by all instances of IFeatureProvider in the - object pool, is checked against \c IWizard::requiredFeatures() + object pool, is checked against \c IWizardFactory::requiredFeatures() and only if all required features are available, the wizard is displayed when creating a new file or project. + If you created JSON-based wizards, the feature set is checked against the + \c featuresRequired setting that is described in + \l{https://doc.qt.io/qtcreator/creator-project-wizards.html} + {Adding New Custom Wizards} in the \QC Manual. + The QtSupport plugin creates an instance of IFeatureProvider and provides Qt specific features for the available versions of Qt. - \sa Core::IWizard - \sa QtSupport::QtVersionManager + \sa Core::IWizardFactory */ /*! diff --git a/src/plugins/coreplugin/find/searchresultwindow.cpp b/src/plugins/coreplugin/find/searchresultwindow.cpp index 1a2e8c271d1..e2a83a71a0e 100644 --- a/src/plugins/coreplugin/find/searchresultwindow.cpp +++ b/src/plugins/coreplugin/find/searchresultwindow.cpp @@ -845,7 +845,8 @@ void SearchResult::setFilter(SearchResultFilter *filter) /*! Notifies the \uicontrol {Search Results} output pane that the current search - has been \a canceled, and the UI should reflect that. + has been \a canceled for the specified \a reason, and the UI should reflect + that. */ void SearchResult::finishSearch(bool canceled, const QString &reason) { diff --git a/src/plugins/coreplugin/iwizardfactory.cpp b/src/plugins/coreplugin/iwizardfactory.cpp index 35713531054..caa664d7e46 100644 --- a/src/plugins/coreplugin/iwizardfactory.cpp +++ b/src/plugins/coreplugin/iwizardfactory.cpp @@ -66,6 +66,17 @@ The wizard creates a new project. */ +/*! + \enum Core::IWizardFactory::WizardFlag + + Holds information about the created projects and files. + + \value PlatformIndependent + The wizard creates projects that run on all platforms. + \value ForceCapitalLetterForFileName + The wizard uses an initial capital letter for the names of new files. +*/ + /*! \fn Core::IWizardFactory::WizardKind Core::IWizardFactory::kind() const Returns what kind of objects are created by the wizard. @@ -237,6 +248,9 @@ FilePath IWizardFactory::runPath(const FilePath &defaultPath) const 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. + + When \a showWizard is \c false, the wizard instance is created and set up + but not actually shown. */ Wizard *IWizardFactory::runWizard(const FilePath &path, QWidget *parent, Id platform, const QVariantMap &variables, diff --git a/src/plugins/coreplugin/locator/ilocatorfilter.cpp b/src/plugins/coreplugin/locator/ilocatorfilter.cpp index f277884cce3..f6b39996d8f 100644 --- a/src/plugins/coreplugin/locator/ilocatorfilter.cpp +++ b/src/plugins/coreplugin/locator/ilocatorfilter.cpp @@ -594,6 +594,7 @@ QString ILocatorFilter::shortcutString() const } /*! + \internal Sets the refresh recipe for refreshing cached data. */ void ILocatorFilter::setRefreshRecipe(const std::optional &recipe) @@ -1277,8 +1278,6 @@ LocatorFilterEntries LocatorFileCachePrivate::generate(const QFuture &futu */ /*! - \fn LocatorFileCache - Constructs an invalid cache. The cache is considered to be in an invalid state after a call to invalidate(), @@ -1382,7 +1381,7 @@ void LocatorFileCache::setFilePathsGenerator(const FilePathsGenerator &generator and sets it to a valid state with the new generator for the passed \a filePaths. The stored generator provider is preserved. - \sa setGenerator + \sa setGeneratorProvider */ void LocatorFileCache::setFilePaths(const FilePaths &filePaths) { diff --git a/src/plugins/coreplugin/session.cpp b/src/plugins/coreplugin/session.cpp index 50873c385c6..7238a09a2ee 100644 --- a/src/plugins/coreplugin/session.cpp +++ b/src/plugins/coreplugin/session.cpp @@ -56,7 +56,8 @@ static bool kIsAutoRestoreLastSessionDefault = false; const char M_SESSION[] = "ProjectExplorer.Menu.Session"; /*! - \class ProjectExplorer::SessionManager + \class Core::SessionManager + \inmodule QtCreator \brief The SessionManager class manages sessions. @@ -164,7 +165,8 @@ bool SessionManager::isLoadingSession() } /*! - Lets other plugins store persistent values within the session file. + Lets other plugins store persistent values specified by \a name and \a value + within the session file. */ void SessionManager::setValue(const QString &name, const QVariant &value) @@ -235,6 +237,9 @@ FilePath SessionManager::sessionNameToFileName(const QString &session) /*! Creates \a session, but does not actually create the file. + + Returns whether the creation was successful. + */ bool SessionManager::createSession(const QString &session) @@ -268,7 +273,10 @@ void SessionManager::showSessionManager() } /*! - \brief Shows a dialog asking the user to confirm deleting the session \p session + Shows a dialog asking the user to confirm the deletion of the specified + \a sessions. + + Returns whether the user confirmed the deletion. */ bool SessionManager::confirmSessionDelete(const QStringList &sessions) { @@ -286,6 +294,8 @@ bool SessionManager::confirmSessionDelete(const QStringList &sessions) /*! Deletes \a session name from session list and the file from disk. + + Returns whether the deletion was successful. */ bool SessionManager::deleteSession(const QString &session) { @@ -515,7 +525,7 @@ QString SessionManager::lastSession() } /*! - Returns the session that was active when Qt Creator was last closed, if any. + Returns the session that was active when \QC was last closed, if any. */ QString SessionManager::startupSession() {