Doc: Fix documentation warnings in Extending Qt Creator Manual

Change-Id: Ic9b1644328e10e147c7f08563b8394418a7d7581
Reviewed-by: hjk <hjk@qt.io>

9 files changed, 33 insertions, 50 deletions

diff --git a/src/plugins/coreplugin/documentmanager.cpp b/src/plugins/coreplugin/documentmanager.cpp
index 4fd4213dbb..15fb2edfdc 100644
--- a/src/plugins/coreplugin/documentmanager.cpp
+++ b/src/plugins/coreplugin/documentmanager.cpp
@@ -607,7 +607,7 @@ QList<IDocument *> DocumentManager::modifiedDocuments()
 }
 
 /*!
-    Treats any subsequent change to \a fileName as an expected file change.
+    Treats any subsequent change to \a filePath as an expected file change.
 
     \sa unexpectFileChange()
 */
@@ -631,7 +631,7 @@ static void updateExpectedState(const FilePath &filePathKey)
 }
 
 /*!
-    Considers all changes to \a fileName unexpected again.
+    Considers all changes to \a filePath unexpected again.
 
     \sa expectFileChange()
 */
diff --git a/src/plugins/coreplugin/editormanager/editormanager.cpp b/src/plugins/coreplugin/editormanager/editormanager.cpp
index df1cc40093..a12c61eb4a 100644
--- a/src/plugins/coreplugin/editormanager/editormanager.cpp
+++ b/src/plugins/coreplugin/editormanager/editormanager.cpp
@@ -256,29 +256,13 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *)
 */
 
 /*!
-    \class EditorManager::FilePathInfo
-    \inheaderfile coreplugin/editormanager/editormanager.h
-    \inmodule QtCreator
-
-    \brief The FilePathInfo class contains information about a file path's
-    special segments.
-
-    File names can have an additional postfix, optionally specifying a line and
-    column number, when opening a file in \QC from the command line or locator.
-    The FilePathInfo class contains the file name, the complete postfix string,
-    and the parsed line and column numbers.
-
-    \sa EditorManager::splitLineAndColumnNumber()
-*/
-
-/*!
-    \fn void EditorManager::currentEditorChanged(IEditor *editor)
+    \fn void Core::EditorManager::currentEditorChanged(Core::IEditor *editor)
 
     This signal is emitted after the current editor changed to \a editor.
 */
 
 /*!
-    \fn void EditorManager::currentDocumentStateChanged()
+    \fn void Core::EditorManager::currentDocumentStateChanged()
 
     This signal is emitted when the meta data of the current document, for
     example file name or modified state, changed.
@@ -287,7 +271,7 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *)
 */
 
 /*!
-    \fn void EditorManager::documentStateChanged(IDocument *document)
+    \fn void Core::EditorManager::documentStateChanged(Core::IDocument *document)
 
     This signal is emitted when the meta data of the \a document, for
     example file name or modified state, changed.
@@ -296,13 +280,13 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *)
 */
 
 /*!
-    \fn void EditorManager::editorCreated(IEditor *editor, const QString &fileName)
+    \fn void Core::EditorManager::editorCreated(Core::IEditor *editor, const QString &fileName)
 
     This signal is emitted after an \a editor was created for \a fileName, but
     before it was opened in an editor view.
 */
 /*!
-    \fn void EditorManager::editorOpened(IEditor *editor)
+    \fn void Core::EditorManager::editorOpened(Core::IEditor *editor)
 
     This signal is emitted after a new \a editor was opened in an editor view.
 
@@ -310,14 +294,14 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *)
 */
 
 /*!
-    \fn void EditorManager::documentOpened(IDocument *document)
+    \fn void Core::EditorManager::documentOpened(Core::IDocument *document)
 
     This signal is emitted after the first editor for \a document opened in an
     editor view.
 */
 
 /*!
-    \fn void EditorManager::editorAboutToClose(IEditor *editor)
+    \fn void Core::EditorManager::editorAboutToClose(Core::IEditor *editor)
 
     This signal is emitted before \a editor is closed. This can be used to free
     resources that were allocated for the editor separately from the editor
@@ -330,7 +314,7 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *)
 */
 
 /*!
-    \fn void EditorManager::editorsClosed(QList<IEditor *> editors)
+    \fn void Core::EditorManager::editorsClosed(QList<Core::IEditor *> editors)
 
     This signal is emitted after the \a editors closed, but before they are
     deleted.
@@ -339,7 +323,7 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *)
 */
 
 /*!
-    \fn void EditorManager::documentClosed(IDocument *document)
+    \fn void Core::EditorManager::documentClosed(Core::IDocument *document)
 
     This signal is emitted after the \a document closed, but before it is deleted.
 */
@@ -349,22 +333,22 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *)
     \internal
 */
 /*!
-    \fn void EditorManager::aboutToSave(IDocument *document)
+    \fn void Core::EditorManager::aboutToSave(Core::IDocument *document)
 
     This signal is emitted before the \a document is saved.
 */
 /*!
-    \fn void EditorManager::saved(IDocument *document)
+    \fn void Core::EditorManager::saved(Core::IDocument *document)
 
     This signal is emitted after the \a document was saved.
 */
 /*!
-    \fn void EditorManager::autoSaved()
+    \fn void Core::EditorManager::autoSaved()
 
     This signal is emitted after auto-save was triggered.
 */
 /*!
-    \fn void EditorManager::currentEditorAboutToChange(IEditor *editor)
+    \fn void Core::EditorManager::currentEditorAboutToChange(Core::IEditor *editor)
 
     This signal is emitted before the current editor changes to \a editor.
 */
@@ -3076,10 +3060,10 @@ IEditor *EditorManager::openEditor(const QString &fileName, Id editorId,
 }
 
 /*!
-    Opens the document specified by \a filePath using the editor type \a
+    Opens the document specified by \a link using the editor type \a
     editorId and the specified \a flags.
 
-    Moves the text cursor to the \a line and \a column.
+    Moves the text cursor to the \e line and \e column specified in \a link.
 
     If \a editorId is \c Id(), the editor type is derived from the file's MIME
     type.
@@ -3147,7 +3131,7 @@ void EditorManager::openEditorAtSearchResult(const SearchResultItem &item,
 }
 
 /*!
-    Returns whether \a fileName is an auto-save file created by \QC.
+    Returns whether \a filePath is an auto-save file created by \QC.
 */
 bool EditorManager::isAutoSaveFile(const QString &filePath)
 {
@@ -3199,7 +3183,7 @@ void EditorManager::addCloseEditorListener(const std::function<bool (IEditor *)>
 /*!
     Asks the user for a list of files to open and returns the choice.
 
-    \sa DocumentManager::getOpenFilePaths()
+    \sa DocumentManager::getOpenFileNames()
 */
 FilePaths EditorManager::getOpenFilePaths()
 {
diff --git a/src/plugins/coreplugin/editormanager/ieditorfactory.cpp b/src/plugins/coreplugin/editormanager/ieditorfactory.cpp
index 702527441f..59d0b988c0 100644
--- a/src/plugins/coreplugin/editormanager/ieditorfactory.cpp
+++ b/src/plugins/coreplugin/editormanager/ieditorfactory.cpp
@@ -162,7 +162,7 @@ const EditorFactoryList IEditorFactory::defaultEditorFactories(const Utils::Mime
 }
 
 /*!
-    Returns the available editor factories for \a fileName in order of
+    Returns the available editor factories for \a filePath in order of
     preference. That is the default order for the document's MIME type but with
     a user overridden default editor first, and the binary editor as the very
     first item if a text document is too large to be opened as a text file.
diff --git a/src/plugins/coreplugin/editormanager/iexternaleditor.cpp b/src/plugins/coreplugin/editormanager/iexternaleditor.cpp
index 99dcbe2703..0680da44a4 100644
--- a/src/plugins/coreplugin/editormanager/iexternaleditor.cpp
+++ b/src/plugins/coreplugin/editormanager/iexternaleditor.cpp
@@ -55,8 +55,7 @@ namespace Core {
 */
 
 /*!
-
-    \fn bool Core::IExternalEditor::startEditor(const QString &fileName, QString *errorMessage) = 0;
+    \fn bool Core::IExternalEditor::startEditor(const Utils::FilePath &fileName, QString *errorMessage)
 
     Opens the editor with \a fileName. Returns \c true on success or \c false
     on failure along with the error in \a errorMessage.
diff --git a/src/plugins/coreplugin/fileiconprovider.cpp b/src/plugins/coreplugin/fileiconprovider.cpp
index 78232af52b..e2149ce35a 100644
--- a/src/plugins/coreplugin/fileiconprovider.cpp
+++ b/src/plugins/coreplugin/fileiconprovider.cpp
@@ -186,7 +186,7 @@ QIcon FileIconProviderImplementation::icon(const FilePath &filePath) const
 }
 
 /*!
-  Returns the icon associated with the file suffix in \a info. If there is none,
+  Returns the icon associated with the file suffix in \a filePath. If there is none,
   the default icon of the operating system is returned.
   */
 
diff --git a/src/plugins/coreplugin/find/searchresultwindow.cpp b/src/plugins/coreplugin/find/searchresultwindow.cpp
index 1e0f46da0e..daeeaee733 100644
--- a/src/plugins/coreplugin/find/searchresultwindow.cpp
+++ b/src/plugins/coreplugin/find/searchresultwindow.cpp
@@ -857,7 +857,7 @@ void SearchResult::setTextToReplace(const QString &textToReplace)
 }
 
 /*!
-    Sets whether replace is enabled and can be triggered by the user
+    Sets whether replace is \a enabled and can be triggered by the user.
 */
 void SearchResult::setReplaceEnabled(bool enabled)
 {
diff --git a/src/plugins/coreplugin/icore.cpp b/src/plugins/coreplugin/icore.cpp
index 82a715f59e..32de08b64e 100644
--- a/src/plugins/coreplugin/icore.cpp
+++ b/src/plugins/coreplugin/icore.cpp
@@ -426,7 +426,7 @@ static QString pathHelper(const QString &rel)
     return '/' + rel;
 }
 /*!
-    Returns the absolute path that is used for resources like
+    Returns the absolute path for the relative path \a rel that is used for resources like
     project templates and the debugger macros.
 
     This abstraction is needed to avoid platform-specific code all over
@@ -443,7 +443,7 @@ FilePath ICore::resourcePath(const QString &rel)
 }
 
 /*!
-    Returns the absolute path in the users directory that is used for
+    Returns the absolute path for the relative path \a rel in the users directory that is used for
     resources like project templates.
 
     Use this function for finding the place for resources that the user may
@@ -468,7 +468,7 @@ FilePath ICore::userResourcePath(const QString &rel)
 }
 
 /*!
-    Returns a writable path that can be used for persistent cache files.
+    Returns a writable path for the relative path \a rel that can be used for persistent cache files.
 */
 FilePath ICore::cacheResourcePath(const QString &rel)
 {
@@ -477,8 +477,8 @@ FilePath ICore::cacheResourcePath(const QString &rel)
 }
 
 /*!
-    Returns the path to resources written by the installer, for example
-    pre-defined kits and toolchains.
+    Returns the path, based on the relative path \a rel, to resources written by the installer,
+    for example pre-defined kits and toolchains.
 */
 FilePath ICore::installerResourcePath(const QString &rel)
 {
@@ -516,8 +516,8 @@ QString ICore::userPluginPath()
 }
 
 /*!
-    Returns the path to the command line tools that are included in the \QC
-    installation.
+    Returns the path, based on the relative path \a rel, to the command line tools that are
+    included in the \QC installation.
  */
 FilePath ICore::libexecPath(const QString &rel)
 {
diff --git a/src/plugins/coreplugin/iversioncontrol.cpp b/src/plugins/coreplugin/iversioncontrol.cpp
index b7d7e63405..6da74e6a50 100644
--- a/src/plugins/coreplugin/iversioncontrol.cpp
+++ b/src/plugins/coreplugin/iversioncontrol.cpp
@@ -61,11 +61,11 @@
  */
 
 /*!
-    \fn Core::IVersionControl::TopicCache::trackFile(const QString &repository)
+    \fn Utils::FilePath Core::IVersionControl::TopicCache::trackFile(const Utils::FilePath &repository)
     Returns the path to the file that invalidates the cache for \a repository when
     the file is modified.
 
-    \fn Core::IVersionControl::TopicCache::refreshTopic(const QString &repository)
+    \fn QString Core::IVersionControl::TopicCache::refreshTopic(const Utils::FilePath &repository)
     Returns the current topic for \a repository.
  */
 
diff --git a/src/plugins/coreplugin/locator/spotlightlocatorfilter.cpp b/src/plugins/coreplugin/locator/spotlightlocatorfilter.cpp
index 4f7e49d2f2..4c43a9832f 100644
--- a/src/plugins/coreplugin/locator/spotlightlocatorfilter.cpp
+++ b/src/plugins/coreplugin/locator/spotlightlocatorfilter.cpp
@@ -180,7 +180,7 @@ static QString defaultCommand()
     return "locate";
 }
 
-/*!
+/*
     For the tools es [1] and locate [2], interpret space as AND operator.
 
     Currently doesn't support fine picking a file with a space in the path by escaped space.