Doc: Fix QDoc warnings in Core plugin dialogs classes

- Fix IOptionsPage class docs
- Mark PromptOverwriteDialog and ReadOnlyFilesDialog

Fixes: QTCREATORBUG-23608
Change-Id: I6a646f0bd68230a7c5f80bd748bda20729f23b74
Reviewed-by: Eike Ziller <eike.ziller@qt.io>

4 files changed, 68 insertions, 31 deletions

diff --git a/doc/qtcreatordev/images/qtcreator-options-dialog.png b/doc/qtcreatordev/images/qtcreator-options-dialog.png
new file mode 100644
index 0000000000..02a446b616
--- /dev/null
+++ b/doc/qtcreatordev/images/qtcreator-options-dialog.png
diff --git a/src/plugins/coreplugin/dialogs/ioptionspage.cpp b/src/plugins/coreplugin/dialogs/ioptionspage.cpp
index 531466d8ad..e2d2ea5e9c 100644
--- a/src/plugins/coreplugin/dialogs/ioptionspage.cpp
+++ b/src/plugins/coreplugin/dialogs/ioptionspage.cpp
@@ -40,11 +40,24 @@
 using namespace Utils;
 
 /*!
+    \class Core::IOptionsPageProvider
+    \inmodule QtCreator
+    \internal
+*/
+/*!
+    \class Core::IOptionsPageWidget
+    \inmodule QtCreator
+    \internal
+*/
+
+/*!
     \class Core::IOptionsPage
-    \mainclass
-    \inmodule Qt Creator
+    \ingroup mainclasses
+    \inmodule QtCreator
     \brief The IOptionsPage class is an interface for providing pages for the
-    \gui Options dialog (called \gui Preferences on Mac OS).
+    \uicontrol Options dialog (called \uicontrol Preferences on \macos).
+
+    \image qtcreator-options-dialog.png
 */
 
 /*!
@@ -64,31 +77,28 @@ using namespace Utils;
     \fn Id IOptionsPage::category() const
 
     Returns the unique id for the category that the options page should be displayed in. This id is
-    used for sorting the list on the left side of the \gui Options dialog.
+    used for sorting the list on the left side of the \uicontrol Options dialog.
 */
 
 /*!
     \fn QString IOptionsPage::displayCategory() const
 
     Returns the translated category name of the options page. This name is displayed in the list on
-    the left side of the \gui Options dialog.
+    the left side of the \uicontrol Options dialog.
 */
 
 /*!
-    \fn QIcon IOptionsPage::categoryIcon() const
-
     Returns the category icon of the options page. This icon is displayed in the list on the left
-    side of the \gui Options dialog.
+    side of the \uicontrol Options dialog.
 */
-
 QIcon Core::IOptionsPage::categoryIcon() const
 {
     return m_categoryIcon.icon();
 }
 
 /*!
-    This sets a callback to create page widgets on demand. The widget will
-    be destroyed on \c finish.
+    Sets the \a widgetCreator callback to create page widgets on demand. The
+    widget will be destroyed on finish().
  */
 void Core::IOptionsPage::setWidgetCreator(const WidgetCreator &widgetCreator)
 {
@@ -96,16 +106,14 @@ void Core::IOptionsPage::setWidgetCreator(const WidgetCreator &widgetCreator)
 }
 
 /*!
-    \fn QWidget *IOptionsPage::widget()
-
-    Returns the widget to show in the \gui Options dialog. You should create a widget lazily here,
+    Returns the widget to show in the \uicontrol Options dialog. You should create a widget lazily here,
     and delete it again in the finish() method. This method can be called multiple times, so you
     should only create a new widget if the old one was deleted.
 
-    Alternatively, use \c setWidgetCreator to set a callback function that is used to
+    Alternatively, use setWidgetCreator() to set a callback function that is used to
     lazily create a widget in time.
 
-    Either override this function in a derived class, or set a \c widgetCreator.
+    Either override this function in a derived class, or set a widget creator.
 */
 
 QWidget *Core::IOptionsPage::widget()
@@ -117,10 +125,12 @@ QWidget *Core::IOptionsPage::widget()
 }
 
 /*!
-    This is called when selecting the \gui Apply button on the options page dialog. It should detect
-    whether any changes were made and store those.
+    Called when selecting the \uicontrol Apply button on the options page dialog.
+    Should detect whether any changes were made and store those.
+
+    Either override this function in a derived class, or set a widget creator.
 
-    Either override this function in a derived class, or set a \c widgetCreator.
+    \sa setWidgetCreator()
 */
 
 void Core::IOptionsPage::apply()
@@ -131,10 +141,12 @@ void Core::IOptionsPage::apply()
 }
 
 /*!
-    This is called directly before the \gui Options dialog closes. Here you should delete the widget that
-    was created in widget() to free resources.
+    Called directly before the \uicontrol Options dialog closes. Here you should
+    delete the widget that was created in widget() to free resources.
 
-    Either override this function in a derived class, or set a \c widgetCreator.
+    Either override this function in a derived class, or set a widget creator.
+
+    \sa setWidgetCreator()
 */
 
 void Core::IOptionsPage::finish()
@@ -146,6 +158,10 @@ void Core::IOptionsPage::finish()
     }
 }
 
+/*!
+    Sets \a categoryIconPath as the path to the category icon of the options
+    page.
+*/
 void Core::IOptionsPage::setCategoryIconPath(const QString &categoryIconPath)
 {
     m_categoryIcon = Icon({{categoryIconPath, Theme::PanelTextColorDark}}, Icon::Tint);
@@ -176,7 +192,7 @@ void Core::IOptionsPage::setCategoryIconPath(const QString &categoryIconPath)
 */
 
 /*!
-    \fn void IOptionsPage::setCategoryIcon(const QString &categoryIcon)
+    \fn void IOptionsPage::setCategoryIcon(const Utils::Icon &categoryIcon)
 
     Sets \a categoryIcon as the category icon of the options page.
 */
@@ -185,7 +201,7 @@ static QList<Core::IOptionsPage *> g_optionsPages;
 
 /*!
     Constructs an options page with the given \a parent and registers it
-    at the global options page pool if \a registerGlobally is true.
+    at the global options page pool if \a registerGlobally is \c true.
 */
 Core::IOptionsPage::IOptionsPage(QObject *parent, bool registerGlobally)
     : QObject(parent)
@@ -195,20 +211,23 @@ Core::IOptionsPage::IOptionsPage(QObject *parent, bool registerGlobally)
 }
 
 /*!
-    Destroys the options page.
+    \internal
  */
 Core::IOptionsPage::~IOptionsPage()
 {
     g_optionsPages.removeOne(this);
 }
 
+/*!
+    Returns a list of all options pages.
+ */
 const QList<Core::IOptionsPage *> Core::IOptionsPage::allOptionsPages()
 {
     return g_optionsPages;
 }
 
 /*!
-    Is used by the \gui Options dialog search filter to match \a searchKeyWord to this options
+    Is used by the \uicontrol Options dialog search filter to match \a searchKeyWord to this options
     page. This defaults to take the widget and then looks for all child labels, check boxes, push
     buttons, and group boxes. Should return \c true when a match is found.
 */
diff --git a/src/plugins/coreplugin/dialogs/promptoverwritedialog.cpp b/src/plugins/coreplugin/dialogs/promptoverwritedialog.cpp
index a9434616c9..d29c56aef0 100644
--- a/src/plugins/coreplugin/dialogs/promptoverwritedialog.cpp
+++ b/src/plugins/coreplugin/dialogs/promptoverwritedialog.cpp
@@ -39,7 +39,9 @@
 enum { FileNameRole = Qt::UserRole + 1 };
 
 /*!
-    \class Core::Internal::PromptOverwriteDialog
+    \class Core::PromptOverwriteDialog
+    \inmodule QtCreator
+    \internal
     \brief The PromptOverwriteDialog class implements a dialog that asks
     users whether they want to overwrite files.
 
diff --git a/src/plugins/coreplugin/dialogs/readonlyfilesdialog.cpp b/src/plugins/coreplugin/dialogs/readonlyfilesdialog.cpp
index d9d11277a8..d41445d8f7 100644
--- a/src/plugins/coreplugin/dialogs/readonlyfilesdialog.cpp
+++ b/src/plugins/coreplugin/dialogs/readonlyfilesdialog.cpp
@@ -133,16 +133,32 @@ ReadOnlyFilesDialogPrivate::~ReadOnlyFilesDialogPrivate()
 using namespace Internal;
 
 /*!
- * \class ReadOnlyFilesDialog
+ * \class Core::ReadOnlyFilesDialog
+ * \inmodule QtCreator
+ * \internal
  * \brief The ReadOnlyFilesDialog class implements a dialog to show a set of
  * files that are classified as not writable.
  *
  * Automatically checks which operations are allowed to make the file writable. These operations
- * are Make Writable which tries to set the file permissions in the file system,
- * Open With Version Control System if the open operation is allowed by the version control system
- * and Save As which is used to save the changes to a document in another file.
+ * are \c MakeWritable (RO_MakeWritable), which tries to set the file permissions in the file system,
+ * \c OpenWithVCS (RO_OpenVCS) if the open operation is allowed by the version control system,
+ * and \c SaveAs (RO_SaveAs), which is used to save the changes to a document under another file
+ * name.
  */
 
+/*! \enum ReadOnlyFilesDialog::ReadOnlyResult
+    This enum holds the operations that are allowed to make the file writable.
+
+     \value RO_Cancel
+            Cancels the operation.
+     \value RO_OpenVCS
+            Opens the file under control of the version control system.
+     \value RO_MakeWritable
+            Sets the file permissions in the file system.
+     \value RO_SaveAs
+            Saves changes to a document under another file name.
+*/
+
 ReadOnlyFilesDialog::ReadOnlyFilesDialog(const Utils::FilePaths &filePaths, QWidget *parent)
     : QDialog(parent)
     , d(new ReadOnlyFilesDialogPrivate(this))