Doc: Fix Editor Manager docs

- Fix issues that cause QDoc warnings for documented classes
- Mark undocumented classes \internal

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

src/plugins/coreplugin/editormanager/documentmodel.cpp

@@ -414,6 +414,18 @@ void DocumentModelPrivate::addEditor(IEditor *editor, bool *isNewDocument)
     }
 }
 
+/*!
+    \class Core::DocumentModel
+    \inmodule QtCreator
+    \internal
+*/
+
+/*!
+    \class Core::DocumentModel::Entry
+    \inmodule QtCreator
+    \internal
+*/
+
 DocumentModel::Entry *DocumentModelPrivate::addSuspendedDocument(const QString &fileName,
                                                                  const QString &displayName,
                                                                  Id id)

src/plugins/coreplugin/editormanager/editormanager.cpp

@@ -133,6 +133,12 @@ using namespace Utils;
 
 //===================EditorManager=====================
 
+/*!
+    \class Core::EditorManagerPlaceHolder
+    \inmodule QtCreator
+    \internal
+*/
+
 EditorManagerPlaceHolder::EditorManagerPlaceHolder(QWidget *parent)
     : QWidget(parent)
 {
@@ -165,6 +171,68 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *)
 
 // ---------------- EditorManager
 
+/*!
+    \class Core::EditorManager
+    \inmodule QtCreator
+    \brief The EditorManager class manages the editors created for files
+    according to their MIME type.
+
+    Whenever a user wants to edit or create a file, the EditorManager scans all
+    IEditorFactory interfaces for suitable editors. The selected IEditorFactory
+    is then asked to create an editor, as determined by the MIME type of the
+    file.
+
+    Users can split the editor view or open the editor in a new window when
+    to work on and view multiple files on the same screen or on multiple
+    screens. For more information, see
+    \l{https://doc.qt.io/qtcreator/creator-coding-navigating.html#splitting-the-editor-view}
+    {Splitting the Editor View}.
+*/
+
+/*!
+    \enum Core::MakeWritableResult
+    \internal
+
+    This enum holds whether the document has successfully been made writable.
+
+    \value OpenedWithVersionControl
+           The document was opened under version control.
+    \value MadeWritable
+           The document was made writable.
+    \value SavedAs
+           The document was saved under another name.
+    \value Failed
+           The document cannot be made writable.
+*/
+
+/*!
+    \enum EditorManager::OpenEditorFlag
+
+    This enum holds settings for opening a file in an editor.
+
+    \value NoFlags
+           Does not use any settings.
+    \value DoNotChangeCurrentEditor
+           Does not switch focus to the newly opened editor.
+    \value IgnoreNavigationHistory
+           Does not add an entry to the navigation history for the
+           opened editor.
+    \value DoNotMakeVisible
+           Does not force the editor to become visible.
+    \value CanContainLineAndColumnNumber
+           If the file path contains line and column numbers, opens
+           the file in an editor and jumps to the line and column.
+    \value OpenInOtherSplit
+           Opens the document in another split of the window.
+    \value DoNotSwitchToDesignMode
+           Opens the document in the current mode.
+    \value DoNotSwitchToEditMode
+           Opens the document in the current mode.
+    \value SwitchSplitIfAlreadyVisible
+           Switches to another split if the document is already
+           visible there.
+*/
+
 static EditorManager *m_instance = nullptr;
 static EditorManagerPrivate *d;
 
@@ -1634,7 +1702,7 @@ void EditorManagerPrivate::closeView(EditorView *view)
     Removes all editors from the view and from the document model, taking care of
     the handling of editors that are the last ones for the document.
     Returns the list of editors that were actually removed from the document model and
-    need to be deleted with EditorManagerPrivate::deleteEditors.
+    need to be deleted with \c EditorManagerPrivate::deleteEditors.
     \internal
 */
 const QList<IEditor *> EditorManagerPrivate::emptyView(EditorView *view)
@@ -1664,7 +1732,7 @@ const QList<IEditor *> EditorManagerPrivate::emptyView(EditorView *view)
 }
 
 /*!
-    Signals editorsClosed and deletes the editors.
+    Signals editorsClosed() and deletes the editors.
     \internal
 */
 void EditorManagerPrivate::deleteEditors(const QList<IEditor *> &editors)
@@ -2412,6 +2480,9 @@ EditorView *EditorManagerPrivate::currentEditorView()
 
 EditorManager *EditorManager::instance() { return m_instance; }
 
+/*!
+    \internal
+*/
 EditorManager::EditorManager(QObject *parent) :
     QObject(parent)
 {
@@ -2420,28 +2491,46 @@ EditorManager::EditorManager(QObject *parent) :
     d->init();
 }
 
+/*!
+    \internal
+*/
 EditorManager::~EditorManager()
 {
     delete d;
     m_instance = nullptr;
 }
 
+/*!
+    Returns the document of the currently active editor.
+*/
 IDocument *EditorManager::currentDocument()
 {
     return d->m_currentEditor ? d->m_currentEditor->document() : nullptr;
 }
 
+/*!
+    Returns the currently active editor.
+*/
 IEditor *EditorManager::currentEditor()
 {
     return d->m_currentEditor;
 }
 
+/*!
+    Closes all open editors. If \a askAboutModifiedEditors is \c true, prompts
+    users to save their changes before closing the editors.
+
+    Returns whether all editors were closed.
+*/
 bool EditorManager::closeAllEditors(bool askAboutModifiedEditors)
 {
     DocumentModelPrivate::removeAllSuspendedEntries();
     return closeDocuments(DocumentModel::openedDocuments(), askAboutModifiedEditors);
 }
 
+/*!
+    Closes all open documents except \a document and pinned files.
+*/
 void EditorManager::closeOtherDocuments(IDocument *document)
 {
     DocumentModelPrivate::removeAllSuspendedEntries(DocumentModelPrivate::DoNotRemovePinnedFiles);
@@ -2455,6 +2544,11 @@ void EditorManager::closeOtherDocuments(IDocument *document)
     closeDocuments(documentsToClose, true);
 }
 
+/*!
+    Closes all open documents except pinned files.
+
+    Returns whether all editors were closed.
+*/
 bool EditorManager::closeAllDocuments()
 {
     // Only close the files that aren't pinned.
@@ -2472,6 +2566,9 @@ void EditorManager::slotCloseCurrentEditorOrDocument()
     d->closeEditorOrDocument(d->m_currentEditor);
 }
 
+/*!
+    Closes all open documents except the current document.
+*/
 void EditorManager::closeOtherDocuments()
 {
     closeOtherDocuments(currentDocument());
@@ -2486,6 +2583,10 @@ static void assignAction(QAction *self, QAction *other)
     self->setIconVisibleInMenu(other->isIconVisibleInMenu());
 }
 
+/*!
+    Adds save, close and other editor context menu items for the document
+    \a entry and editor \a editor to the context menu \a contextMenu.
+*/
 void EditorManager::addSaveAndCloseEditorActions(QMenu *contextMenu, DocumentModel::Entry *entry,
                                                  IEditor *editor)
 {
@@ -2544,6 +2645,10 @@ void EditorManager::addSaveAndCloseEditorActions(QMenu *contextMenu, DocumentMod
     contextMenu->addAction(d->m_closeAllEditorsExceptVisibleContextAction);
 }
 
+/*!
+    Adds the pin editor menu items for the document \a entry to the context menu
+    \a contextMenu.
+*/
 void EditorManager::addPinEditorActions(QMenu *contextMenu, DocumentModel::Entry *entry)
 {
     const QString quotedDisplayName = entry ? Utils::quoteAmpersands(entry->displayName()) : QString();
@@ -2558,6 +2663,10 @@ void EditorManager::addPinEditorActions(QMenu *contextMenu, DocumentModel::Entry
     contextMenu->addAction(d->m_pinAction);
 }
 
+/*!
+    Adds the native directory handling and open with menu items for the document
+    \a entry to the context menu \a contextMenu.
+*/
 void EditorManager::addNativeDirAndOpenWithActions(QMenu *contextMenu, DocumentModel::Entry *entry)
 {
     QTC_ASSERT(contextMenu, return);
@@ -2577,6 +2686,10 @@ void EditorManager::addNativeDirAndOpenWithActions(QMenu *contextMenu, DocumentM
         populateOpenWithMenu(openWith, entry->fileName().toString());
 }
 
+/*!
+    Populates the \uicontrol {Open With} menu \a menu with editors that are
+    suitable for opening the document \a fileName.
+*/
 void EditorManager::populateOpenWithMenu(QMenu *menu, const QString &fileName)
 {
     using EditorFactoryList = QList<IEditorFactory*>;
@@ -2616,37 +2729,59 @@ void EditorManager::populateOpenWithMenu(QMenu *menu, const QString &fileName)
     menu->setEnabled(anyMatches);
 }
 
+/*!
+    Returns reload behavior settings.
+*/
 IDocument::ReloadSetting EditorManager::reloadSetting()
 {
     return d->m_reloadSetting;
 }
 
+/*!
+    Sets editor reaload behavior settings to \a behavior.
+*/
 void EditorManager::setReloadSetting(IDocument::ReloadSetting behavior)
 {
      d->m_reloadSetting = behavior;
 }
 
+/*!
+    Saves the current document.
+*/
 void EditorManager::saveDocument()
 {
     EditorManagerPrivate::saveDocument(currentDocument());
 }
 
+/*!
+    Saves the current document under a different file name.
+*/
 void EditorManager::saveDocumentAs()
 {
     EditorManagerPrivate::saveDocumentAs(currentDocument());
 }
 
+/*!
+    Reverts the current document to its last saved state.
+*/
 void EditorManager::revertToSaved()
 {
     EditorManagerPrivate::revertToSaved(currentDocument());
 }
 
+/*!
+    Closes \a editor. If \a askAboutModifiedEditors is \c true, prompts
+    users to save their changes before closing the editor.
+*/
 void EditorManager::closeEditor(IEditor *editor, bool askAboutModifiedEditors)
 {
     if (editor)
         closeEditors({editor}, askAboutModifiedEditors);
 }
 
+/*!
+    Closes the document specified by \a entry.
+*/
 void EditorManager::closeDocument(DocumentModel::Entry *entry)
 {
     if (!entry)
@@ -2657,6 +2792,11 @@ void EditorManager::closeDocument(DocumentModel::Entry *entry)
         closeDocuments({entry->document});
 }
 
+/*!
+    Closes the documents specified by \a entries.
+
+    Returns whether all documents were closed.
+*/
 bool EditorManager::closeDocuments(const QList<DocumentModel::Entry *> &entries)
 {
     QList<IDocument *> documentsToClose;
@@ -2671,6 +2811,13 @@ bool EditorManager::closeDocuments(const QList<DocumentModel::Entry *> &entries)
     return closeDocuments(documentsToClose);
 }
 
+/*!
+    Closes the editors specified by \a editorsToClose. If
+    \a askAboutModifiedEditors is \c true, prompts users
+    to save their changes before closing the editor.
+
+    Returns whether all editors were closed.
+*/
 bool EditorManager::closeEditors(const QList<IEditor*> &editorsToClose, bool askAboutModifiedEditors)
 {
     return EditorManagerPrivate::closeEditors(editorsToClose,
@@ -2678,12 +2825,20 @@ bool EditorManager::closeEditors(const QList<IEditor*> &editorsToClose, bool ask
                                                                       : EditorManagerPrivate::CloseFlag::CloseWithoutAsking);
 }
 
+/*!
+    Activates the editor for the document specified by \a entry using the editor
+    settings specified by \a flags.
+*/
 void EditorManager::activateEditorForEntry(DocumentModel::Entry *entry, OpenEditorFlags flags)
 {
     EditorManagerPrivate::activateEditorForEntry(EditorManagerPrivate::currentEditorView(),
                                                  entry, flags);
 }
 
+/*!
+    Activates the editor \a editor using the editor settings specified by
+    \a flags.
+*/
 void EditorManager::activateEditor(IEditor *editor, OpenEditorFlags flags)
 {
     QTC_ASSERT(editor, return);
@@ -2694,11 +2849,23 @@ void EditorManager::activateEditor(IEditor *editor, OpenEditorFlags flags)
     EditorManagerPrivate::activateEditor(view, editor, flags);
 }
 
+/*!
+    Activates the editor for the document specified by \a document in the
+    current view using the editor settings specified by \a flags.
+*/
 IEditor *EditorManager::activateEditorForDocument(IDocument *document, OpenEditorFlags flags)
 {
     return EditorManagerPrivate::activateEditorForDocument(EditorManagerPrivate::currentEditorView(), document, flags);
 }
 
+/*!
+    Opens the document specified by \a fileName using the editor type specified
+    by \a editorId and the settings specified by \a flags.
+
+    If \a newEditor is not \c nullptr, and a new editor instance was created,
+    it is set to \c true. If an existing editor instance was used, it is set
+    to \c false.
+*/
 IEditor *EditorManager::openEditor(const QString &fileName, Id editorId,
                                    OpenEditorFlags flags, bool *newEditor)
 {
@@ -2709,6 +2876,15 @@ IEditor *EditorManager::openEditor(const QString &fileName, Id editorId,
                                             fileName, editorId, flags, newEditor);
 }
 
+/*!
+    Opens the document specified by \a fileName to \a line and \a column using
+    the editor type specified by \a editorId and the settings specified by
+    \a flags.
+
+    If \a newEditor is not \c nullptr, and a new editor instance was created,
+    it is set to \c true. If an existing editor instance was used, it is set
+    to \c false.
+*/
 IEditor *EditorManager::openEditorAt(const QString &fileName, int line, int column,
                                      Id editorId, OpenEditorFlags flags, bool *newEditor)
 {
@@ -2719,6 +2895,10 @@ IEditor *EditorManager::openEditorAt(const QString &fileName, int line, int colu
                                               fileName, line, column, editorId, flags, newEditor);
 }
 
+/*!
+    Opens the document at the position of the search hit \a item in the editor
+    using the settings specified by \a flags.
+*/
 void EditorManager::openEditorAtSearchResult(const SearchResultItem &item, OpenEditorFlags flags)
 {
     if (item.path.empty()) {
@@ -2730,6 +2910,14 @@ void EditorManager::openEditorAtSearchResult(const SearchResultItem &item, OpenE
                  item.mainRange.begin.column, Id(), flags);
 }
 
+/*!
+    Returns the file path \a fullFilePath with appended line and column
+    information split into file path, line, and column components.
+
+    The following patterns are supported: \c {filepath.txt:19},
+    \c{filepath.txt:19:12}, \c {filepath.txt+19},
+    \c {filepath.txt+19+12}, and \c {filepath.txt(19)}.
+*/
 EditorManager::FilePathInfo EditorManager::splitLineAndColumnNumber(const QString &fullFilePath)
 {
     // :10:2 GCC/Clang-style
@@ -2760,11 +2948,21 @@ EditorManager::FilePathInfo EditorManager::splitLineAndColumnNumber(const QStrin
     return {filePath, postfix, line, column};
 }
 
+/*!
+    Returns whether \a fileName is an auto-save file created by \QC.
+*/
 bool EditorManager::isAutoSaveFile(const QString &fileName)
 {
     return fileName.endsWith(".autosave");
 }
 
+/*!
+    Opens the document specified by \a fileName in the external editor specified
+    by \a editorId.
+
+    If \a editorId is not the ID of an external editor or the external editor
+    cannot be opened, returns \c false and displays an error message.
+*/
 bool EditorManager::openExternalEditor(const QString &fileName, Id editorId)
 {
     IExternalEditor *ee = Utils::findOrDefault(IExternalEditor::allExternalEditors(),
@@ -2781,21 +2979,23 @@ bool EditorManager::openExternalEditor(const QString &fileName, Id editorId)
 }
 
 /*!
-    \fn EditorManager::addCloseEditorListener
+    Provides a hook for plugins to veto on closing editors.
 
-    \brief The \c EditorManager::addCloseEditorListener function provides
+    When an editor requests a close, all listeners are called. If one of the
-    a hook for plugins to veto on closing editors.
+    \a listener calls returns \c false, the process is aborted and the event is ignored.
-
+    If all calls return \c true, editorAboutToClose() is emitted and the event
-    When an editor requests a close, all listeners are called. If one of these
+    is accepted.
-    calls returns \c false, the process is aborted and the event is ignored.
-    If all calls return \c true, \c EditorManager::editorAboutToClose()
-    is emitted and the event is accepted.
 */
 void EditorManager::addCloseEditorListener(const std::function<bool (IEditor *)> &listener)
 {
     d->m_closeEditorListeners.append(listener);
 }
 
+/*!
+    Asks the user for a list of files to open and returns the choice.
+
+    \sa QFileDialog::getOpenFileNames()
+*/
 QStringList EditorManager::getOpenFileNames()
 {
     QString selectedFilter;
@@ -2836,6 +3036,17 @@ static QString makeTitleUnique(QString *titlePattern)
     return title;
 }
 
+/*!
+    Opens \a contents in an editor of the type \a editorId using the settings
+    specified by \a flags.
+
+    The editor is given a display name based on \a titlePattern. If a
+    non-empty \a uniqueId is specified and an editor with that unique
+     ID is found, it is re-used. Otherwise, a new editor with that
+     unique ID is created.
+
+    Returns the new or re-used editor.
+*/
 IEditor *EditorManager::openEditorWithContents(Id editorId,
                                         QString *titlePattern,
                                         const QByteArray &contents,
@@ -2894,21 +3105,41 @@ IEditor *EditorManager::openEditorWithContents(Id editorId,
     return edt;
 }
 
+/*!
+    Returns whether the document specified by \a filePath should be opened even
+    though it is big. Depending on the settings, might ask the user to decide
+    whether the file should be opened.
+
+    Returns the path to the file that was skipped.
+*/
 bool EditorManager::skipOpeningBigTextFile(const QString &filePath)
 {
     return EditorManagerPrivate::skipOpeningBigTextFile(filePath);
 }
 
+/*!
+    Clears the unique ID of \a document.
+
+    \sa openEditorWithContents()
+*/
 void EditorManager::clearUniqueId(IDocument *document)
 {
     document->setProperty(scratchBufferKey, QVariant());
 }
 
+/*!
+    Saves the changes in \a document.
+
+    Returns whether the operation was successful.
+*/
 bool EditorManager::saveDocument(IDocument *document)
 {
     return EditorManagerPrivate::saveDocument(document);
 }
 
+/*!
+    \internal
+*/
 bool EditorManager::hasSplitter()
 {
     EditorView *view = EditorManagerPrivate::currentEditorView();
@@ -2918,6 +3149,9 @@ bool EditorManager::hasSplitter()
     return area->isSplitter();
 }
 
+/*!
+    Returns the list of visible editors.
+*/
 QList<IEditor*> EditorManager::visibleEditors()
 {
     QList<IEditor *> editors;
@@ -2941,22 +3175,41 @@ QList<IEditor*> EditorManager::visibleEditors()
     return editors;
 }
 
+/*!
+    Closes \a document. If \a askAboutModifiedEditors is \c true, prompts
+    users to save their changes before closing the document.
+
+    Returns whether the document was closed.
+*/
 bool EditorManager::closeDocument(IDocument *document, bool askAboutModifiedEditors)
 {
     return closeDocuments({document}, askAboutModifiedEditors);
 }
 
+/*!
+    Closes \a documents. If \a askAboutModifiedEditors is \c true, prompts
+    users to save their changes before closing the documents.
+
+    Returns whether the documents were closed.
+*/
 bool EditorManager::closeDocuments(const QList<IDocument *> &documents, bool askAboutModifiedEditors)
 {
     return m_instance->closeEditors(DocumentModel::editorsForDocuments(documents), askAboutModifiedEditors);
 }
 
+/*!
+    Adds the current cursor position to the navigation history specified by
+    \a saveState.
+*/
 void EditorManager::addCurrentPositionToNavigationHistory(const QByteArray &saveState)
 {
     EditorManagerPrivate::currentEditorView()->addCurrentPositionToNavigationHistory(saveState);
     EditorManagerPrivate::updateActions();
 }
 
+/*!
+    Sets the location that was last modified to \a editor.
+*/
 void EditorManager::setLastEditLocation(const IEditor* editor)
 {
     IDocument *document = editor->document();
@@ -2973,12 +3226,18 @@ void EditorManager::setLastEditLocation(const IEditor* editor)
     d->m_globalLastEditLocation = location;
 }
 
+/*!
+    Cuts forward in the navigation history.
+*/
 void EditorManager::cutForwardNavigationHistory()
 {
     EditorManagerPrivate::currentEditorView()->cutForwardNavigationHistory();
     EditorManagerPrivate::updateActions();
 }
 
+/*!
+    Goes back in the navigation history.
+*/
 void EditorManager::goBackInNavigationHistory()
 {
     EditorManagerPrivate::currentEditorView()->goBackInNavigationHistory();
@@ -2986,6 +3245,9 @@ void EditorManager::goBackInNavigationHistory()
     return;
 }
 
+/*!
+    Goes forward in the navigation history.
+*/
 void EditorManager::goForwardInNavigationHistory()
 {
     EditorManagerPrivate::currentEditorView()->goForwardInNavigationHistory();
@@ -3006,7 +3268,9 @@ QVector<EditorWindow *> editorWindows(const QList<EditorArea *> &areas)
     return result;
 }
 
-// Save state of all non-temporary editors.
+/*!
+    Returns the serialized state of all non-temporary editors.
+*/
 QByteArray EditorManager::saveState()
 {
     QByteArray bytes;
@@ -3053,6 +3317,11 @@ QByteArray EditorManager::saveState()
     return bytes;
 }
 
+/*!
+    Restores the editor to \a state.
+
+    Returns \c true if the editor state can be restored.
+*/
 bool EditorManager::restoreState(const QByteArray &state)
 {
     closeAllEditors(true);
@@ -3132,6 +3401,10 @@ bool EditorManager::restoreState(const QByteArray &state)
     return true;
 }
 
+/*!
+    Shows the editor status bar \a object with the \a id, \a infoText,
+    \a buttonText, and \a function.
+*/
 void EditorManager::showEditorStatusBar(const QString &id,
                                         const QString &infoText,
                                         const QString &buttonText,
@@ -3143,12 +3416,18 @@ void EditorManager::showEditorStatusBar(const QString &id,
                 id, infoText, buttonText, object, function);
 }
 
+/*!
+    Hides the editor status bar specified by \a id.
+*/
 void EditorManager::hideEditorStatusBar(const QString &id)
 {
     // TODO: what if the current editor view betwenn show and hideEditorStatusBar changed?
     EditorManagerPrivate::currentEditorView()->hideEditorStatusBar(id);
 }
 
+/*!
+    Returns the default text codec for the locale.
+*/
 QTextCodec *EditorManager::defaultTextCodec()
 {
     QSettings *settings = ICore::settings();
@@ -3167,6 +3446,9 @@ QTextCodec *EditorManager::defaultTextCodec()
     return QTextCodec::codecForLocale();
 }
 
+/*!
+    Returns the default line ending as the user specified in the settings.
+*/
 TextFileFormat::LineTerminationMode EditorManager::defaultLineEnding()
 {
     QSettings *settings = ICore::settings();
@@ -3176,13 +3458,16 @@ TextFileFormat::LineTerminationMode EditorManager::defaultLineEnding()
     return static_cast<TextFileFormat::LineTerminationMode>(defaultLineTerminator);
 }
 
+/*!
+    Splits the editor view horizontally into adjacent views.
+*/
 void EditorManager::splitSideBySide()
 {
     EditorManagerPrivate::split(Qt::Horizontal);
 }
 
 /*!
- * Moves focus to "other" split, possibly creating a split if necessary.
+ * Moves focus to another split, creating it if necessary.
  * If there's no split and no other window, a side-by-side split is created.
  * If the current window is split, focus is moved to the next split within this window, cycling.
  * If the current window is not split, focus is moved to the next window.
@@ -3227,16 +3512,25 @@ void EditorManager::gotoOtherSplit()
         EditorManagerPrivate::activateView(nextView);
 }
 
+/*!
+    Returns the maximum file size.
+*/
 qint64 EditorManager::maxTextFileSize()
 {
     return qint64(3) << 24;
 }
 
+/*!
+    Sets the window title addition handler to \a handler.
+*/
 void EditorManager::setWindowTitleAdditionHandler(WindowTitleHandler handler)
 {
     d->m_titleAdditionHandler = handler;
 }
 
+/*!
+    Sets the session title addition handler to \a handler.
+*/
 void EditorManager::setSessionTitleHandler(WindowTitleHandler handler)
 {
     d->m_sessionTitleHandler = handler;

src/plugins/coreplugin/editormanager/editormanager.h

@@ -149,7 +149,7 @@ public:
                                     const QString &infoText,
                                     const QString &buttonText = QString(),
                                     QObject *object = nullptr,
-                                    const std::function<void()> &function = nullptr);
+                                    const std::function<void()> &function = {});
     static void hideEditorStatusBar(const QString &id);
 
     static bool isAutoSaveFile(const QString &fileName);

src/plugins/coreplugin/editormanager/ieditor.cpp

@@ -27,43 +27,95 @@
 
 /*!
   \class Core::IEditor
-  \brief The IEditor class is an interface for providing different editors for
+  \inmodule QtCreator
-  different file types.
+  \brief The IEditor class is an interface for providing suitable editors for
+  documents according to their MIME type.
 
   Classes that implement this interface are for example the editors for
-  C++ files, UI files and resource files.
+  C++ files, UI files, and resource files.
 
-  Whenever a user wants to edit or create a file, the EditorManager scans all
+  Whenever a user wants to edit or create a document, the EditorManager
-  EditorFactoryInterfaces for suitable editors. The selected EditorFactory
+  scans all IEditorFactory interfaces for suitable editors. The selected
-  is then asked to create an editor, which must implement this interface.
+  IEditorFactory is then asked to create an editor, which must implement
+  this interface.
 
-  Guidelines for implementing:
+  \sa Core::IEditorFactory, Core::EditorManager
-  \list
+*/
-  \li \c displayName() is used as a user visible description of the document
-      (usually filename w/o path).
-  \li \c kind() must be the same value as the \c kind() of the corresponding
-      EditorFactory.
-  \li If duplication is supported, you need to ensure that all duplicates
-        return the same \c file().
-  \li QString \c preferredMode() const is the mode the editor manager should
-      activate. Some editors use a special mode (such as \gui Design mode).
-  \endlist
 
-  \sa Core::EditorFactoryInterface Core::IContext
+/*!
+    \fn Core::IDocument *Core::IEditor::document() const
+    Returns the document to open in an editor.
+*/
 
+/*!
+    \fn Core::IEditor *Core::IEditor::duplicate()
+    Duplicates the editor.
+
+    \sa duplicateSupported()
+*/
+
+/*!
+    \fn QByteArray Core::IEditor::saveState() const
+    Saves the state of the document.
+*/
+
+/*!
+    \fn bool Core::IEditor::restoreState(const QByteArray &state)
+    Restores the \a state of the document.
+
+    Returns \c true on success.
+*/
+
+/*!
+    \fn int Core::IEditor::currentLine() const
+    Returns the current line in the document.
+*/
+
+/*!
+    \fn int Core::IEditor::currentColumn() const
+    Returns the current column in the document.
+*/
+
+/*!
+    \fn void Core::IEditor::gotoLine(int line, int column = 0, bool centerLine = true)
+    Goes to \a line and \a column in the document. If \a centerLine is
+    \c true, centers the line in the editor.
+*/
+
+/*!
+    \fn QWidget Core::IEditor::toolBar()
+    Returns the toolbar for the editor.
+
+    The editor toolbar is located at the top of the editor view. The editor
+    toolbar is context sensitive and shows items relevant to the document
+    currently open in the editor.
+*/
+
+/*! \fn bool Core::IEditor::isDesignModePreferred() const
+    Indicates whether the document should be opened in the Design mode.
+    Returns \c false unless Design mode is preferred.
 */
 
 namespace Core {
 
+/*!
+    \internal
+*/
 IEditor::IEditor(QObject *parent)
     : IContext(parent), m_duplicateSupported(false)
 {}
 
+/*!
+    Returns whether duplication is supported.
+*/
 bool IEditor::duplicateSupported() const
 {
     return m_duplicateSupported;
 }
 
+/*!
+    Sets whether duplication is supported to \a duplicatesSupported.
+*/
 void IEditor::setDuplicateSupported(bool duplicatesSupported)
 {
     m_duplicateSupported = duplicatesSupported;

src/plugins/coreplugin/editormanager/ieditorfactory.cpp

@@ -34,19 +34,86 @@
 
 namespace Core {
 
+/*!
+    \class Core::IEditorFactory
+    \inmodule QtCreator
+    \brief The IEditorFactory class creates suitable editors for documents
+    according to their MIME type.
+
+    Whenever a user wants to edit or create a document, the EditorManager
+    scans all IEditorFactory interfaces for suitable editors. The selected
+    IEditorFactory is then asked to create an editor.
+
+    Guidelines for the implementation:
+
+    \list
+        \li displayName() is used as a user visible description of the editor
+            type that is created. For example, the name displayed in the
+            \uicontrol {Open With} menu.
+        \li If duplication is supported (IEditor::duplicateSupported()), you
+            need to ensure that all duplicates return the same document().
+    \endlist
+
+    \sa Core::IEditor, Core::EditorManager
+*/
+
+/*!
+    \fn void Core::IEditorFactory::addMimeType(const QString &mimeType)
+    Adds \a mimeType to the list of MIME types supported by this editor type.
+*/
+
+/*!
+    \fn QString Core::IEditorFactory::displayName() const
+    Returns a user-visible description of the editor type.
+*/
+
+/*!
+    \fn Core::Id Core::IEditorFactory::id() const
+    Returns the ID of the factory or editor type.
+*/
+
+/*!
+    \fn QString Core::IEditorFactory::mimeTypes() const
+    Returns a list of MIME types that the editor supports.
+*/
+
+/*!
+    \fn void Core::IEditorFactory::setDisplayName(const QString &displayName)
+    Sets the \a displayName of the factory or editor type.
+*/
+
+/*!
+    \fn void Core::IEditorFactory::setId(Id id)
+    Sets the \a id of the factory or editor type.
+*/
+
+/*!
+    \fn void Core::IEditorFactory::setMimeTypes(const QStringList &mimeTypes)
+    Sets the MIME types supported by the editor to \a mimeTypes.
+*/
+
 static QList<IEditorFactory *> g_editorFactories;
 static QHash<Utils::MimeType, IEditorFactory *> g_userPreferredEditorFactories;
 
+/*!
+    \internal
+*/
 IEditorFactory::IEditorFactory()
 {
     g_editorFactories.append(this);
 }
 
+/*!
+    \internal
+*/
 IEditorFactory::~IEditorFactory()
 {
     g_editorFactories.removeOne(this);
 }
 
+/*!
+    \internal
+*/
 const EditorFactoryList IEditorFactory::allEditorFactories()
 {
     return g_editorFactories;
@@ -54,7 +121,7 @@ const EditorFactoryList IEditorFactory::allEditorFactories()
 
 /*!
     Returns all available editors for this \a mimeType in the default order
-    (editors ordered by mime type hierarchy).
+    (editors ordered by MIME type hierarchy).
 */
 const EditorFactoryList IEditorFactory::defaultEditorFactories(const Utils::MimeType &mimeType)
 {
@@ -66,9 +133,9 @@ const EditorFactoryList IEditorFactory::defaultEditorFactories(const Utils::Mime
 
 /*!
     Returns the available editors for \a fileName in order of preference.
-    That is the default order for the file's MIME type but with a user overridden default
+    That is the default order for the document's MIME type but with a user
-    editor first, and if the file is a too large text file, with the binary editor as the
+    overridden default editor first, and if the document is a too large
-    very first.
+    text file, with the binary editor as the very first.
 */
 const EditorFactoryList IEditorFactory::preferredEditorFactories(const QString &fileName)
 {
@@ -95,22 +162,38 @@ const EditorFactoryList IEditorFactory::preferredEditorFactories(const QString &
     return factories;
 }
 
+/*!
+    Creates an editor.
+
+    Either override this in a subclass, or set the function to use for
+    creating an editor instance with setEditorCreator().
+*/
 IEditor *IEditorFactory::createEditor() const
 {
     QTC_ASSERT(m_creator, return nullptr);
     return m_creator();
 }
 
+/*!
+    Sets the function that is used to create an editor instance in
+    createEditor() by default to \a creator.
+*/
 void IEditorFactory::setEditorCreator(const std::function<IEditor *()> &creator)
 {
     m_creator = creator;
 }
 
+/*!
+    \internal
+*/
 QHash<Utils::MimeType, Core::IEditorFactory *> Core::Internal::userPreferredEditorFactories()
 {
     return g_userPreferredEditorFactories;
 }
 
+/*!
+    \internal
+*/
 void Internal::setUserPreferredEditorFactories(const QHash<Utils::MimeType, IEditorFactory *> &factories)
 {
     g_userPreferredEditorFactories = factories;

src/plugins/coreplugin/editormanager/iexternaleditor.cpp

@@ -31,25 +31,31 @@ namespace Core {
 
 /*!
     \class Core::IExternalEditor
-    \mainclass
+    \inmodule QtCreator
+    \ingroup mainclasses
 
     \brief The IExternalEditor class enables registering an external
-    editor in the \gui{Open With} dialog.
+    editor in the \uicontrol{Open With} dialog.
 */
 
 /*!
-    \fn IExternalEditor::IExternalEditor(QObject *parent)
+    \fn QString Core::IExternalEditor::displayName() const
-    \internal
+    Returns a user-visible description of the editor type.
 */
 
 /*!
-    \fn QStringList IExternalEditor::mimeTypes() const
+    \fn Core::Id Core::IExternalEditor::id() const
-    Returns the mime type the editor supports
+    Returns the ID of the factory or editor type.
+*/
+
+/*!
+    \fn QStringList Core::IExternalEditor::mimeTypes() const
+    Returns a list of MIME types that the editor supports
 */
 
 /*!
 
-    \fn bool IExternalEditor::startEditor(const QString &fileName, QString *errorMessage) = 0;
+    \fn bool Core::IExternalEditor::startEditor(const QString &fileName, QString *errorMessage) = 0;
 
     Opens the editor with \a fileName. Returns \c true on success or \c false
     on failure along with the error in \a errorMessage.
@@ -57,22 +63,35 @@ namespace Core {
 
 static QList<IExternalEditor *> g_externalEditors;
 
+/*!
+    \internal
+*/
 IExternalEditor::IExternalEditor(QObject *parent)
     : QObject(parent)
 {
     g_externalEditors.append(this);
 }
 
+/*!
+    \internal
+*/
 IExternalEditor::~IExternalEditor()
 {
     g_externalEditors.removeOne(this);
 }
 
+/*!
+    Returns all available external editors.
+*/
 const ExternalEditorList IExternalEditor::allExternalEditors()
 {
     return g_externalEditors;
 }
 
+/*!
+    Returns all external editors available for this \a mimeType in the default
+    order (editors ordered by MIME type hierarchy).
+*/
 const ExternalEditorList IExternalEditor::externalEditors(const Utils::MimeType &mimeType)
 {
     ExternalEditorList rc;