From e3581a3961dd4298122a8ede9488af11f2acfa08 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Fri, 20 Mar 2020 16:28:17 +0100 Subject: [PATCH] Doc: Fix Document Manager docs Task-number: QTCREATORBUG-23620 Change-Id: I7c70398008e9c8855beef9b2239e1a7431904076 Reviewed-by: Eike Ziller --- src/plugins/coreplugin/documentmanager.cpp | 248 ++++++++++++--------- src/plugins/coreplugin/documentmanager.h | 6 - 2 files changed, 146 insertions(+), 108 deletions(-) diff --git a/src/plugins/coreplugin/documentmanager.cpp b/src/plugins/coreplugin/documentmanager.cpp index 993c2244fbe..f7a8340d9ef 100644 --- a/src/plugins/coreplugin/documentmanager.cpp +++ b/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 - 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, - the status of the IDocument object - will be adjusted accordingly. Furthermore, on application exit the user will - be asked to save all modified files. + The DocumentManager service monitors a set of IDocument objects. + + This section uses the following terminology: + + \list + \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 - \c blockFileChange(), and enabled again by \c unblockFileChange(). + file system. The monitoring for an IDocument can be blocked by + 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 - files: \c saveModifiedFiles() and \c saveModifiedFilesSilently(). Both take a list - of FileInterfaces as an argument, and return the list of files which were - _not_ saved. + The DocumentManager service also provides convenience functions + for saving documents, such as \l saveModifiedDocuments() and + \l saveModifiedDocumentsSilently(). They present users with a + 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), - the files are added to a file system watcher that notifies the file manager - about file changes. + Adds a list of \a documents to the collection. If \a addWatcher is \c true + (the default), the documents' files are added to a file system watcher that + notifies the document manager about file changes. */ void DocumentManager::addDocuments(const QList &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 - watcher can report the event during the next event loop run). \a from needs to be an absolute file path. + the file system watcher can report the event during the next event loop run). + + \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 - information to avoid annoying the user with "file has been removed" - popups. + by calling \l IDocument::setFilePath(), and update the cached time and + permission information to avoid annoying the user with \e {the file has + 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 - (the default), - the file is added to a file system watcher that notifies the file manager - about file changes. + Adds \a document to the collection. If \a addWatcher is \c true + (the default), the document's file is added to a file system watcher + that notifies the document manager 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 - argument to \a addDocument() set. + Returns \c true if the document had the \c addWatcher argument to + 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(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 - if the file system is case insensitive (in the host OS settings).) + 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. Resolves symlinks if \a resolveMode is ResolveLinks. */ QString DocumentManager::filePathKey(const QString &filePath, ResolveMode resolveMode) @@ -563,9 +582,9 @@ QList 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 - successfully. + Silently saves all documents and returns \c true if all modified documents + are saved successfully. - This method will try to avoid showing dialogs to the user, but can do so anyway (e.g. if - a file is not writeable). + This method tries to avoid showing dialogs to the user, but can do so anyway + (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. - \a FailedToClose will contain a list of documents that could not be saved if passed into the - method. + 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. */ bool DocumentManager::saveAllModifiedDocumentsSilently(bool *canceled, QList *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 - a file is not writeable). + This method tries to avoid showing dialogs to the user, but can do so anyway + (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. - \a FailedToClose will contain a list of documents that could not be saved if passed into the - method. + 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. */ bool DocumentManager::saveModifiedDocumentsSilently(const QList &documents, bool *canceled, @@ -882,14 +902,15 @@ bool DocumentManager::saveModifiedDocumentsSilently(const QList &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 - a file is not writeable). + This method tries to avoid showing dialogs to the user, but can do so anyway + (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 *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 - should be saved. + Presents a dialog with all modified 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 - of the dialogs that he interacted with (the method will also return false in this case). - The \a alwaysSaveMessage will show an additional checkbox asking in the dialog. The state of - 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 - method. + The dialog text can be set using \a message. If users canceled any + of the dialogs they interacted with, \a canceled is set and the + method returns \c false. + + The \a alwaysSaveMessage shows an additional checkbox in the dialog. + 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 - of the dialogs that he interacted with (the method will also return false in this case). - The \a alwaysSaveMessage will show an additional checkbox asking in the dialog. The state of - 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 - method. + The dialog text can be set using \a message. If users canceled any + of the dialogs they interacted with, \a canceled is set and the + method returns \c false. + + The \a alwaysSaveMessage shows an additional checkbox in the dialog. + 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 &documents, const QString &message, bool *canceled, @@ -940,17 +970,21 @@ bool DocumentManager::saveModifiedDocuments(const QList &documents, } /*! - Presents a dialog with the one \a document to the user and will ask him whether he wants it - saved. + Presents a dialog with the \a document to users and asks them whether + 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 - of the dialogs that he interacted with (the method will also return false in this case). - The \a alwaysSaveMessage will show an additional checkbox asking in the dialog. The state of - 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 - method. + The dialog text can be set using \a message. If users canceled any + of the dialogs they interacted with, \a canceled is set and the + method returns \c false. + + The \a alwaysSaveMessage shows an additional checkbox in the dialog. + 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 - a current file, uses that, otherwise if there is a default location for - new files, uses that, otherwise uses the last visited directory. + Returns the initial directory for a new file dialog. If there is a current + document associated with a file, uses that. Or if there is a default location + for new files, uses that. Otherwise, uses the last visited directory. - \sa setFileDialogLastVisitedDirectory - \sa setDefaultLocationForNewFiles + \sa setFileDialogLastVisitedDirectory(), 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) { diff --git a/src/plugins/coreplugin/documentmanager.h b/src/plugins/coreplugin/documentmanager.h index 92323efdc33..66ca54cd2e1 100644 --- a/src/plugins/coreplugin/documentmanager.h +++ b/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: