Doc: Fix Document Manager docs

Task-number: QTCREATORBUG-23620
Change-Id: I7c70398008e9c8855beef9b2239e1a7431904076
Reviewed-by: Eike Ziller <eike.ziller@qt.io>

src/plugins/coreplugin/documentmanager.cpp

@@ -71,29 +71,47 @@ static Q_LOGGING_CATEGORY(log, "qtc.core.documentmanager", QtWarningMsg)
 
 /*!
   \class Core::DocumentManager
-  \mainclass
+  \ingroup mainclasses
+  \inmodule QtCreator
   \inheaderfile documentmanager.h
-  \brief The DocumentManager class manages a set of IDocument objects.
+  \brief The DocumentManager class manages a set of documents.
 
-  The DocumentManager service monitors a set of IDocument objects. Plugins
+  The DocumentManager service monitors a set of IDocument objects.
-  should register files they work with at the service. The files the IDocument
+
-  objects point to will be monitored at filesystem level. If a file changes,
+  This section uses the following terminology:
-  the status of the IDocument object
+
-  will be adjusted accordingly. Furthermore, on application exit the user will
+  \list
-  be asked to save all modified files.
+    \li A \e file means a collection of data stored on a disk under a name
+        (that is, the usual meaning of the term \e file in computing).
+    \li A \e document holds content open in Qt Creator. If it corresponds to a
+        file, it might differ from it, because it was modified. But a document
+        might not correspond to a file at all. For example, diff viewer
+        documents or Git blame or log records are created and displayed by
+        Qt Creator upon request.
+    \li An \a editor provides a view into a document that is actually visible
+        to the user and potentially allows editing the document. Multiple
+        editors can open views into the same document.
+  \endlist
+
+  Plugins should register documents they work with at the document management
+  service. The files the IDocument objects point to will be monitored at
+  file system level. If a file changes on disk, the status of the IDocument
+  object will be adjusted accordingly. On application exit the user will be
+  asked to save all modified documents.
 
   Different IDocument objects in the set can point to the same file in the
-  filesystem. The monitoring for an IDocument can be blocked by
+  file system. The monitoring for an IDocument can be blocked by
-  \c blockFileChange(), and enabled again by \c unblockFileChange().
+  using the \l Core::FileChangeBlocker class.
 
   The functions \c expectFileChange() and \c unexpectFileChange() mark a file change
   as expected. On expected file changes all IDocument objects are notified to reload
   themselves.
 
-  The DocumentManager service also provides two convenience functions for saving
+  The DocumentManager service also provides convenience functions
-  files: \c saveModifiedFiles() and \c saveModifiedFilesSilently(). Both take a list
+  for saving documents, such as \l saveModifiedDocuments() and
-  of FileInterfaces as an argument, and return the list of files which were
+  \l saveModifiedDocumentsSilently(). They present users with a
-  _not_ saved.
+  dialog that lists all modified documents and asks them which
+  documents should be saved.
 
   The service also manages the list of recent files to be shown to the user.
 
@@ -315,9 +333,9 @@ static void addFileInfo(IDocument *document)
 }
 
 /*!
-    Adds a list of IDocument's to the collection. If \a addWatcher is true (the default),
+    Adds a list of \a documents to the collection. If \a addWatcher is \c true
-    the files are added to a file system watcher that notifies the file manager
+    (the default), the documents' files are added to a file system watcher that
-    about file changes.
+    notifies the document manager about file changes.
 */
 void DocumentManager::addDocuments(const QList<IDocument *> &documents, bool addWatcher)
 {
@@ -411,15 +429,17 @@ static void dump()
 */
 
 /*!
-    Tells the file manager that a file has been renamed on disk from within \QC.
+    Tells the document manager that a file has been renamed from \a from to
+    \a to on disk from within \QC.
 
     Needs to be called right after the actual renaming on disk (that is, before
-    the file system
+    the file system watcher can report the event during the next event loop run).
-    watcher can report the event during the next event loop run). \a from needs to be an absolute file path.
+
+    \a from needs to be an absolute file path.
     This will notify all IDocument objects pointing to that file of the rename
-    by calling \c IDocument::rename(), and update the cached time and permission
+    by calling \l IDocument::setFilePath(), and update the cached time and
-    information to avoid annoying the user with "file has been removed"
+    permission information to avoid annoying the user with \e {the file has
-    popups.
+    been removed} popups.
 */
 void DocumentManager::renamedFile(const QString &from, const QString &to)
 {
@@ -454,10 +474,9 @@ void DocumentManager::filePathChanged(const FilePath &oldName, const FilePath &n
 }
 
 /*!
-    Adds an IDocument object to the collection. If \a addWatcher is \c true
+    Adds \a document to the collection. If \a addWatcher is \c true
-    (the default),
+    (the default), the document's file is added to a file system watcher
-    the file is added to a file system watcher that notifies the file manager
+    that notifies the document manager about file changes.
-    about file changes.
 */
 void DocumentManager::addDocument(IDocument *document, bool addWatcher)
 {
@@ -473,10 +492,10 @@ void DocumentManager::documentDestroyed(QObject *obj)
 }
 
 /*!
-    Removes an IDocument object from the collection.
+    Removes \a document from the collection.
 
-    Returns \c true if the file specified by \a document had the \a addWatcher
+    Returns \c true if the document had the \c addWatcher argument to
-    argument to \a addDocument() set.
+    addDocument() set.
 */
 bool DocumentManager::removeDocument(IDocument *document)
 {
@@ -494,7 +513,7 @@ bool DocumentManager::removeDocument(IDocument *document)
 }
 
 /* Slot reacting on IDocument::changed. We need to check if the signal was sent
-   because the file was saved under different name. */
+   because the document was saved under different name. */
 void DocumentManager::checkForNewFileName()
 {
     auto document = qobject_cast<IDocument *>(sender());
@@ -528,8 +547,8 @@ QString DocumentManager::cleanAbsoluteFilePath(const QString &filePath, ResolveM
 
 /*!
     Returns a representation of \a filePath that can be used as a key for maps.
-    (A cleaned absolute file path in portable form, that is all lowercase
+    It is a cleaned absolute file path in portable form, that is all lowercase
-    if the file system is case insensitive (in the host OS settings).)
+    if the file system is case insensitive in the host OS settings.
     Resolves symlinks if \a resolveMode is ResolveLinks.
 */
 QString DocumentManager::filePathKey(const QString &filePath, ResolveMode resolveMode)
@@ -563,9 +582,9 @@ QList<IDocument *> DocumentManager::modifiedDocuments()
 }
 
 /*!
-    Any subsequent change to \a fileName is treated as an expected file change.
+    Treats any subsequent change to \a fileName as an expected file change.
 
-    \see DocumentManager::unexpectFileChange(const QString &fileName)
+    \sa unexpectFileChange()
 */
 void DocumentManager::expectFileChange(const QString &fileName)
 {
@@ -587,9 +606,9 @@ static void updateExpectedState(const QString &filePathKey)
 }
 
 /*!
-    Any changes to \a fileName are unexpected again.
+    Considers all changes to \a fileName unexpected again.
 
-    \see DocumentManager::expectFileChange(const QString &fileName)
+    \sa expectFileChange()
 */
 void DocumentManager::unexpectFileChange(const QString &fileName)
 {
@@ -808,7 +827,7 @@ QString DocumentManager::getSaveFileNameWithExtension(const QString &title, cons
 }
 
 /*!
-    Asks the user for a new file name (\gui {Save File As}) for \a document.
+    Asks the user for a new file name (\uicontrol {Save File As}) for \a document.
 */
 QString DocumentManager::getSaveAsFileName(const IDocument *document)
 {
@@ -842,15 +861,15 @@ QString DocumentManager::getSaveAsFileName(const IDocument *document)
 }
 
 /*!
-    Silently saves all documents and will return true if all modified documents were saved
+    Silently saves all documents and returns \c true if all modified documents
-    successfully.
+    are saved successfully.
 
-    This method will try to avoid showing dialogs to the user, but can do so anyway (e.g. if
+    This method tries to avoid showing dialogs to the user, but can do so anyway
-    a file is not writeable).
+    (e.g. if a file is not writeable).
 
-    \a Canceled will be set if the user canceled any of the dialogs that he interacted with.
+    If users canceled any of the dialogs they interacted with, \a canceled
-    \a FailedToClose will contain a list of documents that could not be saved if passed into the
+    is set. If passed to the method, \a failedToClose returns a list of
-    method.
+    documents that could not be saved.
 */
 bool DocumentManager::saveAllModifiedDocumentsSilently(bool *canceled,
                                                        QList<IDocument *> *failedToClose)
@@ -859,14 +878,15 @@ bool DocumentManager::saveAllModifiedDocumentsSilently(bool *canceled,
 }
 
 /*!
-    Silently saves \a documents and will return true if all of them were saved successfully.
+    Silently saves \a documents and returns \c true if all of them were saved
+    successfully.
 
-    This method will try to avoid showing dialogs to the user, but can do so anyway (e.g. if
+    This method tries to avoid showing dialogs to the user, but can do so anyway
-    a file is not writeable).
+    (e.g. if a file is not writeable).
 
-    \a Canceled will be set if the user canceled any of the dialogs that he interacted with.
+    If users canceled any of the dialogs they interacted with, \a canceled
-    \a FailedToClose will contain a list of documents that could not be saved if passed into the
+    is set. If passed to the method, \a failedToClose returns a list of
-    method.
+    documents that could not be saved.
 */
 bool DocumentManager::saveModifiedDocumentsSilently(const QList<IDocument *> &documents,
                                                     bool *canceled,
@@ -882,14 +902,15 @@ bool DocumentManager::saveModifiedDocumentsSilently(const QList<IDocument *> &do
 }
 
 /*!
-    Silently saves a \a document and will return true if it was saved successfully.
+    Silently saves \a document and returns \c true if it was saved successfully.
 
-    This method will try to avoid showing dialogs to the user, but can do so anyway (e.g. if
+    This method tries to avoid showing dialogs to the user, but can do so anyway
-    a file is not writeable).
+    (e.g. if a file is not writeable).
+
+    If users canceled any of the dialogs they interacted with, \a canceled
+    is set. If passed to the method, \a failedToClose returns a list of
+    documents that could not be saved.
 
-    \a Canceled will be set if the user canceled any of the dialogs that he interacted with.
-    \a FailedToClose will contain a list of documents that could not be saved if passed into the
-    method.
 */
 bool DocumentManager::saveModifiedDocumentSilently(IDocument *document, bool *canceled,
                                                    QList<IDocument *> *failedToClose)
@@ -898,17 +919,21 @@ bool DocumentManager::saveModifiedDocumentSilently(IDocument *document, bool *ca
 }
 
 /*!
-    Presents a dialog with all modified documents to the user and will ask him which of these
+    Presents a dialog with all modified documents to users and asks them which
-    should be saved.
+    of these should be saved.
 
-    This method may show additional dialogs to the user, e.g. if a file is not writeable).
+    This method may show additional dialogs to the user, e.g. if a file is
+    not writeable.
 
-    The dialog text can be set using \a message. \a Canceled will be set if the user canceled any
+    The dialog text can be set using \a message. If users canceled any
-    of the dialogs that he interacted with (the method will also return false in this case).
+    of the dialogs they interacted with, \a canceled is set and the
-    The \a alwaysSaveMessage will show an additional checkbox asking in the dialog. The state of
+    method returns \c false.
-    this checkbox will be written into \a alwaysSave if set.
+
-    \a FailedToClose will contain a list of documents that could not be saved if passed into the
+    The \a alwaysSaveMessage shows an additional checkbox in the dialog.
-    method.
+    The state of this checkbox is written into \a alwaysSave if set.
+
+    If passed to the method, \a failedToClose returns a list of
+    documents that could not be saved.
 */
 bool DocumentManager::saveAllModifiedDocuments(const QString &message, bool *canceled,
                                                const QString &alwaysSaveMessage, bool *alwaysSave,
@@ -919,16 +944,21 @@ bool DocumentManager::saveAllModifiedDocuments(const QString &message, bool *can
 }
 
 /*!
-    Presents a dialog with \a documents to the user and will ask him which of these should be saved.
+    Presents a dialog with \a documents to users and asks them which
+    of these should be saved.
 
-    This method may show additional dialogs to the user, e.g. if a file is not writeable).
+    This method may show additional dialogs to the user, e.g. if a file is
+    not writeable.
 
-    The dialog text can be set using \a message. \a Canceled will be set if the user canceled any
+    The dialog text can be set using \a message. If users canceled any
-    of the dialogs that he interacted with (the method will also return false in this case).
+    of the dialogs they interacted with, \a canceled is set and the
-    The \a alwaysSaveMessage will show an additional checkbox asking in the dialog. The state of
+    method returns \c false.
-    this checkbox will be written into \a alwaysSave if set.
+
-    \a FailedToClose will contain a list of documents that could not be saved if passed into the
+    The \a alwaysSaveMessage shows an additional checkbox in the dialog.
-    method.
+    The state of this checkbox is written into \a alwaysSave if set.
+
+    If passed to the method, \a failedToClose returns a list of
+    documents that could not be saved.
 */
 bool DocumentManager::saveModifiedDocuments(const QList<IDocument *> &documents,
                                             const QString &message, bool *canceled,
@@ -940,17 +970,21 @@ bool DocumentManager::saveModifiedDocuments(const QList<IDocument *> &documents,
 }
 
 /*!
-    Presents a dialog with the one \a document to the user and will ask him whether he wants it
+    Presents a dialog with the \a document to users and asks them whether
-    saved.
+    it should be saved.
 
-    This method may show additional dialogs to the user, e.g. if the file is not writeable).
+    This method may show additional dialogs to the user, e.g. if a file is
+    not writeable.
 
-    The dialog text can be set using \a message. \a Canceled will be set if the user canceled any
+    The dialog text can be set using \a message. If users canceled any
-    of the dialogs that he interacted with (the method will also return false in this case).
+    of the dialogs they interacted with, \a canceled is set and the
-    The \a alwaysSaveMessage will show an additional checkbox asking in the dialog. The state of
+    method returns \c false.
-    this checkbox will be written into \a alwaysSave if set.
+
-    \a FailedToClose will contain a list of documents that could not be saved if passed into the
+    The \a alwaysSaveMessage shows an additional checkbox in the dialog.
-    method.
+    The state of this checkbox is written into \a alwaysSave if set.
+
+    If passed to the method, \a failedToClose returns a list of
+    documents that could not be saved.
 */
 bool DocumentManager::saveModifiedDocument(IDocument *document, const QString &message, bool *canceled,
                                            const QString &alwaysSaveMessage, bool *alwaysSave,
@@ -969,7 +1003,7 @@ void DocumentManager::showFilePropertiesDialog(const FilePath &filePath)
 /*!
     Asks the user for a set of file names to be opened. The \a filters
     and \a selectedFilter arguments are interpreted like in
-    \c QFileDialog::getOpenFileNames(). \a pathIn specifies a path to open the
+    QFileDialog::getOpenFileNames(). \a pathIn specifies a path to open the
     dialog in if that is not overridden by the user's policy.
 */
 
@@ -1259,7 +1293,7 @@ void DocumentManager::checkForReload()
 /*!
     Adds the \a fileName to the list of recent files. Associates the file to
     be reopened with the editor that has the specified \a editorId, if possible.
-    \a editorId defaults to the empty id, which lets \QC figure out
+    \a editorId defaults to the empty ID, which lets \QC figure out
     the best editor itself.
 */
 void DocumentManager::addToRecentFiles(const QString &fileName, Id editorId)
@@ -1346,12 +1380,11 @@ void readSettings()
 
 /*!
 
-  Returns the initial directory for a new file dialog. If there is
+  Returns the initial directory for a new file dialog. If there is a current
-  a current file, uses that, otherwise if there is a default location for
+  document associated with a file, uses that. Or if there is a default location
-  new files, uses that, otherwise uses the last visited directory.
+  for new files, uses that. Otherwise, uses the last visited directory.
 
-  \sa setFileDialogLastVisitedDirectory
+  \sa setFileDialogLastVisitedDirectory(), setDefaultLocationForNewFiles()
-  \sa setDefaultLocationForNewFiles
 */
 
 QString DocumentManager::fileDialogInitialDirectory()
@@ -1366,9 +1399,9 @@ QString DocumentManager::fileDialogInitialDirectory()
 
 /*!
 
-  Sets the default location for new files
+  Returns the default location for new files.
 
-  \sa fileDialogInitialDirectory
+  \sa fileDialogInitialDirectory()
 */
 QString DocumentManager::defaultLocationForNewFiles()
 {
@@ -1376,7 +1409,7 @@ QString DocumentManager::defaultLocationForNewFiles()
 }
 
 /*!
- Returns the default location for new files
+ Sets the default \a location for new files.
  */
 void DocumentManager::setDefaultLocationForNewFiles(const QString &location)
 {
@@ -1387,7 +1420,7 @@ void DocumentManager::setDefaultLocationForNewFiles(const QString &location)
 
   Returns the directory for projects. Defaults to HOME.
 
-  \sa setProjectsDirectory, setUseProjectsDirectory
+  \sa setProjectsDirectory(), setUseProjectsDirectory()
 */
 
 FilePath DocumentManager::projectsDirectory()
@@ -1397,9 +1430,9 @@ FilePath DocumentManager::projectsDirectory()
 
 /*!
 
-  Sets the directory for projects.
+  Sets the \a directory for projects.
 
-  \sa projectsDirectory, useProjectsDirectory
+  \sa projectsDirectory(), useProjectsDirectory()
 */
 
 void DocumentManager::setProjectsDirectory(const FilePath &directory)
@@ -1415,7 +1448,7 @@ void DocumentManager::setProjectsDirectory(const FilePath &directory)
     Returns whether the directory for projects is to be used or whether the user
     chose to use the current directory.
 
-  \sa setProjectsDirectory, setUseProjectsDirectory
+  \sa setProjectsDirectory(), setUseProjectsDirectory()
 */
 
 bool DocumentManager::useProjectsDirectory()
@@ -1425,9 +1458,10 @@ bool DocumentManager::useProjectsDirectory()
 
 /*!
 
-  Sets whether the directory for projects is to be used.
+  Sets whether the directory for projects is to be used to
+  \a useProjectsDirectory.
 
-  \sa projectsDirectory, useProjectsDirectory
+  \sa projectsDirectory(), useProjectsDirectory()
 */
 
 void DocumentManager::setUseProjectsDirectory(bool useProjectsDirectory)
@@ -1439,7 +1473,7 @@ void DocumentManager::setUseProjectsDirectory(bool useProjectsDirectory)
 
   Returns the last visited directory of a file dialog.
 
-  \sa setFileDialogLastVisitedDirectory, fileDialogInitialDirectory
+  \sa setFileDialogLastVisitedDirectory(), fileDialogInitialDirectory()
 
 */
 
@@ -1450,10 +1484,10 @@ QString DocumentManager::fileDialogLastVisitedDirectory()
 
 /*!
 
-  Sets the last visited directory of a file dialog that will be remembered
+  Sets the last visited \a directory of a file dialog that will be remembered
   for the next one.
 
-  \sa fileDialogLastVisitedDirectory, fileDialogInitialDirectory
+  \sa fileDialogLastVisitedDirectory(), fileDialogInitialDirectory()
 
   */
 
@@ -1469,6 +1503,16 @@ void DocumentManager::notifyFilesChangedInternally(const QStringList &files)
 
 // -------------- FileChangeBlocker
 
+/*!
+    \class Core::FileChangeBlocker
+    \inmodule QtCreator
+    \brief The FileChangeBlocker class blocks all change notifications to all
+    IDocument objects that match the given filename.
+
+    Additionally, the class unblocks in the destructor. To also reload the
+    IDocument object in the destructor, set modifiedReload() to \c true.
+*/
+
 FileChangeBlocker::FileChangeBlocker(const QString &fileName)
     : m_fileName(fileName)
 {

src/plugins/coreplugin/documentmanager.h

@@ -167,12 +167,6 @@ private:
     friend class Core::Internal::DocumentManagerPrivate;
 };
 
-/*! The FileChangeBlocker blocks all change notifications to all IDocument * that
-    match the given filename. And unblocks in the destructor.
-
-    To also reload the IDocument in the destructor class set modifiedReload to true
-
-  */
 class CORE_EXPORT FileChangeBlocker
 {
 public: