Add missing documentation for EditorManager

And tweak related documentation a bit.

Change-Id: Id71d6ed0ddf1bd81f605a6b17b51ed3d9fee9485
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>

src/plugins/coreplugin/editormanager/editormanager.cpp

@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2020 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of Qt Creator.
@@ -125,18 +125,31 @@ static const char preferredEditorFactoriesKey[] = "EditorManager/PreferredEditor
 
 static const char scratchBufferKey[] = "_q_emScratchBuffer";
 
-using namespace Core;
 using namespace Core::Internal;
 using namespace Utils;
 
+namespace Core {
+
 //===================EditorManager=====================
 
 /*!
     \class Core::EditorManagerPlaceHolder
+    \inheaderfile coreplugin/editormanager/editormanager.h
     \inmodule QtCreator
-    \internal
+    \ingroup mainclasses
+
+    \brief The EditorManagerPlaceHolder class is used to integrate an editor
+    area into a \l{Core::IMode}{mode}.
+
+    Create an instance of EditorManagerPlaceHolder and integrate it into your
+    mode widget's layout, to add the main editor area into your mode. The best
+    place for the editor area is the central widget of a QMainWindow.
+    Examples are the Edit and Debug modes.
 */
 
+/*!
+    Creates an EditorManagerPlaceHolder with the specified \a parent.
+*/
 EditorManagerPlaceHolder::EditorManagerPlaceHolder(QWidget *parent)
     : QWidget(parent)
 {
@@ -145,6 +158,9 @@ EditorManagerPlaceHolder::EditorManagerPlaceHolder(QWidget *parent)
     setFocusProxy(EditorManagerPrivate::mainEditorArea());
 }
 
+/*!
+    \internal
+*/
 EditorManagerPlaceHolder::~EditorManagerPlaceHolder()
 {
     // EditorManager will be deleted in ~MainWindow()
@@ -155,6 +171,9 @@ EditorManagerPlaceHolder::~EditorManagerPlaceHolder()
     }
 }
 
+/*!
+    \internal
+*/
 void EditorManagerPlaceHolder::showEvent(QShowEvent *)
 {
     QWidget *previousFocus = nullptr;
@@ -187,13 +206,16 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *)
     screens. For more information, see
     \l{https://doc.qt.io/qtcreator/creator-coding-navigating.html#splitting-the-editor-view}
     {Splitting the Editor View}.
+
+    Plugins use the EditorManager to open documents in editors or close them,
+    and to get notified when documents are opened, closed or saved.
 */
 
 /*!
-    \enum Core::MakeWritableResult
+    \enum Core::Internal::MakeWritableResult
     \internal
 
-    This enum holds whether the document has successfully been made writable.
+    This enum specifies whether the document has successfully been made writable.
 
     \value OpenedWithVersionControl
            The document was opened under version control.
@@ -208,7 +230,7 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *)
 /*!
     \enum EditorManager::OpenEditorFlag
 
-    This enum holds settings for opening a file in an editor.
+    This enum specifies settings for opening a file in an editor.
 
     \value NoFlags
            Does not use any settings.
@@ -233,6 +255,120 @@ void EditorManagerPlaceHolder::showEvent(QShowEvent *)
            visible there.
 */
 
+/*!
+    \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)
+
+    This signal is emitted after the current editor changed to \a editor.
+*/
+
+/*!
+    \fn void EditorManager::currentDocumentStateChanged()
+
+    This signal is emitted when the meta data of the current document, for
+    example file name or modified state, changed.
+
+    \sa IDocument::changed()
+*/
+
+/*!
+    \fn void EditorManager::documentStateChanged(IDocument *document)
+
+    This signal is emitted when the meta data of the \a document, for
+    example file name or modified state, changed.
+
+    \sa IDocument::changed()
+*/
+
+/*!
+    \fn void EditorManager::editorCreated(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)
+
+    This signal is emitted after a new \a editor was opened in an editor view.
+
+    Usually the more appropriate signal to listen to is documentOpened().
+*/
+
+/*!
+    \fn void EditorManager::documentOpened(IDocument *document)
+
+    This signal is emitted after the first editor for \a document opened in an
+    editor view.
+*/
+
+/*!
+    \fn void EditorManager::editorAboutToClose(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
+    itself. It cannot be used to prevent the editor from closing. See
+    addCloseEditorListener() for that.
+
+    Usually the more appropriate signal to listen to is documentClosed().
+
+    \sa addCloseEditorListener()
+*/
+
+/*!
+    \fn void EditorManager::editorsClosed(QList<IEditor *> editors)
+
+    This signal is emitted after the \a editors closed, but before they are
+    deleted.
+
+    Usually the more appropriate signal to listen to is documentClosed().
+*/
+
+/*!
+    \fn void EditorManager::documentClosed(IDocument *document)
+
+    This signal is emitted after the \a document closed, but before it is deleted.
+*/
+/*!
+    \fn void EditorManager::findOnFileSystemRequest(const QString &path)
+
+    \internal
+*/
+/*!
+    \fn void EditorManager::aboutToSave(IDocument *document)
+
+    This signal is emitted before the \a document is saved.
+*/
+/*!
+    \fn void EditorManager::saved(IDocument *document)
+
+    This signal is emitted after the \a document was saved.
+*/
+/*!
+    \fn void EditorManager::autoSaved()
+
+    This signal is emitted after auto-save was triggered.
+*/
+/*!
+    \fn void EditorManager::currentEditorAboutToChange(IEditor *editor)
+
+    This signal is emitted before the current editor changes to \a editor.
+*/
+
 static EditorManager *m_instance = nullptr;
 static EditorManagerPrivate *d;
 
@@ -2492,8 +2628,13 @@ EditorView *EditorManagerPrivate::currentEditorView()
     return view;
 }
 
-
+/*!
-EditorManager *EditorManager::instance() { return m_instance; }
+    Returns the pointer to the instance. Only use for connecting to signals.
+*/
+EditorManager *EditorManager::instance()
+{
+    return m_instance;
+}
 
 /*!
     \internal
@@ -2517,6 +2658,8 @@ EditorManager::~EditorManager()
 
 /*!
     Returns the document of the currently active editor.
+
+    \sa currentEditor()
 */
 IDocument *EditorManager::currentDocument()
 {
@@ -2525,6 +2668,8 @@ IDocument *EditorManager::currentDocument()
 
 /*!
     Returns the currently active editor.
+
+    \sa currentDocument()
 */
 IEditor *EditorManager::currentEditor()
 {
@@ -2572,7 +2717,9 @@ bool EditorManager::closeAllDocuments()
     return EditorManager::closeDocuments(entriesToClose);
 }
 
-// SLOT connected to action
+/*!
+    \internal
+*/
 void EditorManager::slotCloseCurrentEditorOrDocument()
 {
     if (!d->m_currentEditor)
@@ -2753,6 +2900,8 @@ IDocument::ReloadSetting EditorManager::reloadSetting()
 }
 
 /*!
+    \internal
+
     Sets editor reaload behavior settings to \a behavior.
 */
 void EditorManager::setReloadSetting(IDocument::ReloadSetting behavior)
@@ -2809,6 +2958,10 @@ bool EditorManager::closeDocuments(const QList<DocumentModel::Entry *> &entries)
     to save their changes before closing the editor.
 
     Returns whether all editors were closed.
+
+    Usually closeDocuments() is the better alternative.
+
+    \sa closeDocuments()
 */
 bool EditorManager::closeEditors(const QList<IEditor*> &editorsToClose, bool askAboutModifiedEditors)
 {
@@ -2818,8 +2971,8 @@ bool EditorManager::closeEditors(const QList<IEditor*> &editorsToClose, bool ask
 }
 
 /*!
-    Activates the editor for the document specified by \a entry using the editor
+    Activates an editor for the document specified by \a entry in the active
-    settings specified by \a flags.
+    split using the specified \a flags.
 */
 void EditorManager::activateEditorForEntry(DocumentModel::Entry *entry, OpenEditorFlags flags)
 {
@@ -2828,8 +2981,9 @@ void EditorManager::activateEditorForEntry(DocumentModel::Entry *entry, OpenEdit
 }
 
 /*!
-    Activates the editor \a editor using the editor settings specified by
+    Activates the \a editor in the active split using the specified \a flags.
-    \a flags.
+
+    \sa currentEditor()
 */
 void EditorManager::activateEditor(IEditor *editor, OpenEditorFlags flags)
 {
@@ -2842,8 +2996,8 @@ void EditorManager::activateEditor(IEditor *editor, OpenEditorFlags flags)
 }
 
 /*!
-    Activates the editor for the document specified by \a document in the
+    Activates an editor for the \a document in the active split using the
-    current view using the editor settings specified by \a flags.
+    specified \a flags.
 */
 IEditor *EditorManager::activateEditorForDocument(IDocument *document, OpenEditorFlags flags)
 {
@@ -2851,12 +3005,19 @@ IEditor *EditorManager::activateEditorForDocument(IDocument *document, OpenEdito
 }
 
 /*!
-    Opens the document specified by \a fileName using the editor type specified
+    Opens the document specified by \a fileName using the editor type \a
-    by \a editorId and the settings specified by \a flags.
+    editorId and the specified \a flags.
+
+    If \a editorId is \c Id(), the editor type is derived from the file's MIME
+    type.
 
     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.
+
+    \sa openEditorAt()
+    \sa openEditorWithContents()
+    \sa openExternalEditor()
 */
 IEditor *EditorManager::openEditor(const QString &fileName, Id editorId,
                                    OpenEditorFlags flags, bool *newEditor)
@@ -2869,13 +3030,23 @@ IEditor *EditorManager::openEditor(const QString &fileName, Id editorId,
 }
 
 /*!
-    Opens the document specified by \a fileName to \a line and \a column using
+    Opens the document specified by \a fileName using the editor type \a
-    the editor type specified by \a editorId and the settings specified by
+    editorId and the specified \a flags.
-    \a flags.
+
+    Moves the text cursor to the \a line and \a column.
+
+    If \a editorId is \c Id(), the editor type is derived from the file's MIME
+    type.
 
     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.
+
+    \sa openEditor()
+    \sa openEditorAtSearchResult()
+    \sa openEditorWithContents()
+    \sa openExternalEditor()
+    \sa IEditor::gotoLine()
 */
 IEditor *EditorManager::openEditorAt(const QString &fileName, int line, int column,
                                      Id editorId, OpenEditorFlags flags, bool *newEditor)
@@ -2888,8 +3059,17 @@ IEditor *EditorManager::openEditorAt(const QString &fileName, int line, int colu
 }
 
 /*!
-    Opens the document at the position of the search hit \a item in the editor
+    Opens the document at the position of the search result \a item using the
-    using the settings specified by \a flags.
+    editor type \a editorId and the specified \a flags.
+
+    If \a editorId is \c Id(), the editor type is derived from the file's MIME
+    type.
+
+    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.
+
+    \sa openEditorAt()
 */
 void EditorManager::openEditorAtSearchResult(const SearchResultItem &item,
                                              Id editorId,
@@ -2910,8 +3090,8 @@ void EditorManager::openEditorAtSearchResult(const SearchResultItem &item,
 }
 
 /*!
-    Returns the file path \a fullFilePath with appended line and column
+    Returns the file path \a fullFilePath split into its file path, line
-    information split into file path, line, and column components.
+    number, and column number components.
 
     The following patterns are supported: \c {filepath.txt:19},
     \c{filepath.txt:19:12}, \c {filepath.txt+19},
@@ -2959,8 +3139,10 @@ bool EditorManager::isAutoSaveFile(const QString &fileName)
     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
+    Returns \c false and displays an error message if \a editorId is not the ID
-    cannot be opened, returns \c false and displays an error message.
+    of an external editor or the external editor cannot be opened.
+
+    \sa openEditor()
 */
 bool EditorManager::openExternalEditor(const QString &fileName, Id editorId)
 {
@@ -2978,12 +3160,12 @@ bool EditorManager::openExternalEditor(const QString &fileName, Id editorId)
 }
 
 /*!
-    Provides a hook for plugins to veto on closing editors.
+    Adds \a listener to the hooks that are asked if editors may be closed.
 
-    When an editor requests a close, all listeners are called. If one of the
+    When an editor requests to close, all listeners are called. If one of the
-    \a listener calls returns \c false, the process is aborted and the event is ignored.
+    calls returns \c false, the process is aborted and the event is ignored. If
-    If all calls return \c true, editorAboutToClose() is emitted and the event
+    all calls return \c true, editorAboutToClose() is emitted and the event is
-    is accepted.
+    accepted.
 */
 void EditorManager::addCloseEditorListener(const std::function<bool (IEditor *)> &listener)
 {
@@ -2993,7 +3175,7 @@ void EditorManager::addCloseEditorListener(const std::function<bool (IEditor *)>
 /*!
     Asks the user for a list of files to open and returns the choice.
 
-    \sa QFileDialog::getOpenFileNames()
+    \sa DocumentManager::getOpenFileNames()
 */
 QStringList EditorManager::getOpenFileNames()
 {
@@ -3036,15 +3218,16 @@ static QString makeTitleUnique(QString *titlePattern)
 }
 
 /*!
-    Opens \a contents in an editor of the type \a editorId using the settings
+    Opens \a contents in an editor of the type \a editorId using the specified
-    specified by \a flags.
+    \a flags.
 
-    The editor is given a display name based on \a titlePattern. If a
+    The editor is given a display name based on \a titlePattern. If a non-empty
-    non-empty \a uniqueId is specified and an editor with that unique
+    \a uniqueId is specified and an editor with that unique ID is found, it is
-     ID is found, it is re-used. Otherwise, a new editor with that
+    re-used. Otherwise, a new editor with that unique ID is created.
-     unique ID is created.
 
     Returns the new or re-used editor.
+
+    \sa clearUniqueId()
 */
 IEditor *EditorManager::openEditorWithContents(Id editorId,
                                         QString *titlePattern,
@@ -3106,10 +3289,8 @@ IEditor *EditorManager::openEditorWithContents(Id editorId,
 
 /*!
     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
+    though it is big. Depending on the settings this might ask the user to
-    whether the file should be opened.
+    decide whether the file should be opened.
-
-    Returns the path to the file that was skipped.
 */
 bool EditorManager::skipOpeningBigTextFile(const QString &filePath)
 {
@@ -3186,8 +3367,12 @@ bool EditorManager::closeDocuments(const QList<IDocument *> &documents, bool ask
 }
 
 /*!
-    Adds the current cursor position to the navigation history specified by
+    Adds the current cursor position specified by \a saveState to the
-    \a saveState.
+    navigation history. If \a saveState is \l{QByteArray::isNull()}{null} (the
+    default), the current state of the active editor is used. Otherwise \a
+    saveState must be a valid state of the active editor.
+
+    \sa IEditor::saveState()
 */
 void EditorManager::addCurrentPositionToNavigationHistory(const QByteArray &saveState)
 {
@@ -3197,6 +3382,7 @@ void EditorManager::addCurrentPositionToNavigationHistory(const QByteArray &save
 
 /*!
     Sets the location that was last modified to \a editor.
+    Used for \uicontrol{Window} > \uicontrol{Go to Last Edit}.
 */
 void EditorManager::setLastEditLocation(const IEditor* editor)
 {
@@ -3215,7 +3401,11 @@ void EditorManager::setLastEditLocation(const IEditor* editor)
 }
 
 /*!
-    Cuts forward in the navigation history.
+    Cuts the forward part of the navigation history, so the user cannot
+    \uicontrol{Go Forward} anymore (until the user goes backward again).
+
+    \sa goForwardInNavigationHistory()
+    \sa addCurrentPositionToNavigationHistory()
 */
 void EditorManager::cutForwardNavigationHistory()
 {
@@ -3225,6 +3415,9 @@ void EditorManager::cutForwardNavigationHistory()
 
 /*!
     Goes back in the navigation history.
+
+    \sa goForwardInNavigationHistory()
+    \sa addCurrentPositionToNavigationHistory()
 */
 void EditorManager::goBackInNavigationHistory()
 {
@@ -3235,6 +3428,9 @@ void EditorManager::goBackInNavigationHistory()
 
 /*!
     Goes forward in the navigation history.
+
+    \sa goBackInNavigationHistory()
+    \sa addCurrentPositionToNavigationHistory()
 */
 void EditorManager::goForwardInNavigationHistory()
 {
@@ -3257,7 +3453,12 @@ QVector<EditorWindow *> editorWindows(const QList<EditorArea *> &areas)
 }
 
 /*!
-    Returns the serialized state of all non-temporary editors.
+    \internal
+
+    Returns the serialized state of all non-temporary editors, the split layout
+    and external editor windows.
+
+    \sa restoreState()
 */
 QByteArray EditorManager::saveState()
 {
@@ -3306,9 +3507,13 @@ QByteArray EditorManager::saveState()
 }
 
 /*!
-    Restores the editor to \a state.
+    \internal
 
-    Returns \c true if the editor state can be restored.
+    Restores the \a state of the split layout, editor windows and editors.
+
+    Returns \c true if the state can be restored.
+
+    \sa saveState()
 */
 bool EditorManager::restoreState(const QByteArray &state)
 {
@@ -3390,8 +3595,7 @@ bool EditorManager::restoreState(const QByteArray &state)
 }
 
 /*!
-    Shows the editor status bar \a object with the \a id, \a infoText,
+    \internal
-    \a buttonText, and \a function.
 */
 void EditorManager::showEditorStatusBar(const QString &id,
                                         const QString &infoText,
@@ -3405,7 +3609,7 @@ void EditorManager::showEditorStatusBar(const QString &id,
 }
 
 /*!
-    Hides the editor status bar specified by \a id.
+    \internal
 */
 void EditorManager::hideEditorStatusBar(const QString &id)
 {
@@ -3414,7 +3618,7 @@ void EditorManager::hideEditorStatusBar(const QString &id)
 }
 
 /*!
-    Returns the default text codec for the locale.
+    Returns the default text codec as the user specified in the settings.
 */
 QTextCodec *EditorManager::defaultTextCodec()
 {
@@ -3501,7 +3705,7 @@ void EditorManager::gotoOtherSplit()
 }
 
 /*!
-    Returns the maximum file size.
+    Returns the maximum file size that should be opened in a text editor.
 */
 qint64 EditorManager::maxTextFileSize()
 {
@@ -3509,6 +3713,8 @@ qint64 EditorManager::maxTextFileSize()
 }
 
 /*!
+    \internal
+
     Sets the window title addition handler to \a handler.
 */
 void EditorManager::setWindowTitleAdditionHandler(WindowTitleHandler handler)
@@ -3517,6 +3723,8 @@ void EditorManager::setWindowTitleAdditionHandler(WindowTitleHandler handler)
 }
 
 /*!
+    \internal
+
     Sets the session title addition handler to \a handler.
 */
 void EditorManager::setSessionTitleHandler(WindowTitleHandler handler)
@@ -3524,12 +3732,18 @@ void EditorManager::setSessionTitleHandler(WindowTitleHandler handler)
     d->m_sessionTitleHandler = handler;
 }
 
+/*!
+    \internal
+*/
 void EditorManager::updateWindowTitles()
 {
     foreach (EditorArea *area, d->m_editorAreas)
         emit area->windowTitleNeedsUpdate();
 }
 
+/*!
+    \internal
+*/
 void EditorManager::setWindowTitleVcsTopicHandler(WindowTitleHandler handler)
 {
     d->m_titleVcsTopicHandler = handler;
@@ -3610,3 +3824,5 @@ void CorePlugin::testSplitLineAndColumnNumber_data()
 }
 
 #endif // WITH_TESTS
+
+} // namespace Core

src/plugins/coreplugin/editormanager/ieditor.cpp

@@ -91,14 +91,21 @@ namespace Core {
     \fn int IEditor::currentLine() const
 
     Returns the current line in the document, if appropriate. The default
-    implementation returns \c 0.
+    implementation returns \c 0. Line numbers start at \c 1 for the first line.
+
+    \sa currentColumn()
+    \sa gotoLine()
 */
 
 /*!
     \fn int IEditor::currentColumn() const
 
     Returns the current column in the document, if appropriate. The default
-    implementation returns \c 0.
+    implementation returns \c 0. Column numbers start at \c 0 for the first
+    column.
+
+    \sa currentLine()
+    \sa gotoLine()
 */
 
 /*!
@@ -107,7 +114,13 @@ namespace Core {
     Goes to \a line and \a column in the document. If \a centerLine is
     \c true, centers the line in the editor.
 
+    Line numbers start at \c 1 for the first line, column numbers start at \c 0
+    for the first column.
+
     The default implementation does nothing.
+
+    \sa currentLine()
+    \sa currentColumn()
 */
 
 /*!

src/plugins/coreplugin/idocument.cpp

@@ -308,7 +308,7 @@ Id IDocument::id() const
     The default implementation does nothing and returns
     CannotHandle.
 
-    \sa EditorManager::open()
+    \sa EditorManager::openEditor()
     \sa shouldAutoSave()
     \sa setFilePath()
 */