Improve IEditor documentation

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

src/plugins/coreplugin/editormanager/ieditor.cpp

@@ -26,66 +26,93 @@
 #include "ieditor.h"
 
 /*!
-  \class Core::IEditor
-  \inheaderfile coreplugin/editormanager/ieditor.h
-  \inmodule QtCreator
+    \class Core::IEditor
+    \inheaderfile coreplugin/editormanager/ieditor.h
+    \inmodule QtCreator
 
-  \brief The IEditor class is an interface for providing suitable editors for
-  documents according to their MIME type.
+    \brief The IEditor class provides an interface for editing an open document
+    in \QC.
 
-  Classes that implement this interface are for example the editors for
-  C++ files, UI files, and resource files.
+    IEditor instances are usually created by a corresponding IEditorFactory.
 
-  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, which must implement
-  this interface.
+    An IEditor instance provides an editor widget for a single IDocument via
+    the IContext::widget() method. If the the editor type supports it, multiple
+    editors can be opened for the same document. Multiple IEditor instances
+    share ownership of the same IDocument instance in that case.
 
-  \sa Core::IEditorFactory, Core::EditorManager
+    The IEditor::toolBar() is integrated into the toolbar above the editor
+    widget, next to the document drop down.
+
+    \sa Core::IEditorFactory, Core::EditorManager
+*/
+
+namespace Core {
+
+/*!
+    \fn IDocument *IEditor::document() const
+
+    Returns the document that is edited by this editor. The editor owns the
+    document. If the editor supports splitting, all editors created with
+    duplicate() share ownership of the document.
+
+    This must never return \c nullptr.
 */
 
 /*!
-    \fn Core::IDocument *Core::IEditor::document() const
-    Returns the document to open in an editor.
-*/
+    \fn IEditor *IEditor::duplicate()
 
-/*!
-    \fn Core::IEditor *Core::IEditor::duplicate()
-    Duplicates the editor.
+    Returns a duplicate of the editor, for example when the user splits the
+    editor view. The default implementation returns \c nullptr.
 
     \sa duplicateSupported()
 */
 
 /*!
-    \fn QByteArray Core::IEditor::saveState() const
-    Saves the state of the document.
+    \fn QByteArray IEditor::saveState() const
+
+    Returns the state of the editor, like scroll and cursor position, as a
+    QByteArray. This is used for restoring the state for example after the
+    document was closed (manually or automatically) and re-opened later. The
+    default implementation returns an empty QByteArray.
+
+    \sa restoreState()
 */
 
 /*!
-    \fn bool Core::IEditor::restoreState(const QByteArray &state)
-    Restores the \a state of the document.
+    \fn void IEditor::restoreState(const QByteArray &state)
 
-    Returns \c true on success.
+    Restores the \a state of the editor. The default implementation does
+    nothing.
+
+    \sa saveState()
 */
 
 /*!
-    \fn int Core::IEditor::currentLine() const
-    Returns the current line in the document.
+    \fn int IEditor::currentLine() const
+
+    Returns the current line in the document, if appropriate. The default
+    implementation returns \c 0.
 */
 
 /*!
-    \fn int Core::IEditor::currentColumn() const
-    Returns the current column in the document.
+    \fn int IEditor::currentColumn() const
+
+    Returns the current column in the document, if appropriate. The default
+    implementation returns \c 0.
 */
 
 /*!
-    \fn void Core::IEditor::gotoLine(int line, int column = 0, bool centerLine = true)
+    \fn void IEditor::gotoLine(int line, int column, bool centerLine)
+
     Goes to \a line and \a column in the document. If \a centerLine is
     \c true, centers the line in the editor.
+
+    The default implementation does nothing.
 */
 
 /*!
-    \fn QWidget Core::IEditor::toolBar()
+    \fn QWidget IEditor::toolBar()
+
     Returns the toolbar for the editor.
 
     The editor toolbar is located at the top of the editor view. The editor
@@ -93,22 +120,30 @@
     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.
+/*!
+    \fn bool IEditor::isDesignModePreferred() const
+
+    Returns whether the document should be opened in the Design mode by
+    default. This requires design mode to support that document type. The
+    default implementation returns \c false.
 */
 
-namespace Core {
-
 /*!
-    \internal
+    Creates an IEditor.
+
+    Implementations must create a corresponding document, or share an existing
+    document with another IEditor.
 */
 IEditor::IEditor()
     : m_duplicateSupported(false)
 {}
 
 /*!
-    Returns whether duplication is supported.
+    Returns whether duplication is supported, for example when the user splits
+    the editor view.
+
+    \sa duplicate()
+    \sa setDuplicateSupported()
 */
 bool IEditor::duplicateSupported() const
 {
@@ -117,6 +152,11 @@ bool IEditor::duplicateSupported() const
 
 /*!
     Sets whether duplication is supported to \a duplicatesSupported.
+
+    The default is \c false.
+
+    \sa duplicate()
+    \sa duplicateSupported()
 */
 void IEditor::setDuplicateSupported(bool duplicatesSupported)
 {