From 392690e565441b0caea86a4e3deac885ea197522 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Thu, 6 Feb 2020 16:56:16 +0100 Subject: Doc: Fix Utils::QrcCache and Utils::QrcParser docs - Move class docs away from the internal namespace - Add missing docs - Remove \brief commands and fix capitalization and punctuation Task-number: QTCREATORBUG-23544 Change-Id: I60440a603e73c78447fd4d923d8631debeb25116 Reviewed-by: hjk --- src/libs/utils/qrcparser.cpp | 155 ++++++++++++++++++++++++++++++++----------- 1 file changed, 116 insertions(+), 39 deletions(-) diff --git a/src/libs/utils/qrcparser.cpp b/src/libs/utils/qrcparser.cpp index dcb704abc4..2dfb9a19c2 100644 --- a/src/libs/utils/qrcparser.cpp +++ b/src/libs/utils/qrcparser.cpp @@ -45,27 +45,7 @@ Q_LOGGING_CATEGORY(qrcParserLog, "qtc.qrcParser", QtWarningMsg) namespace Utils { namespace Internal { -/*! - * \class QrcParser - * \brief Parses one or more qrc files, and keeps their content cached - * - * A Qrc resource contains files read from the filesystem but organized in a possibly different way. - * - * To easily describe that with a simple structure we use a map from qrc paths to the paths in the - * filesystem. - * By using a map we can easily find all qrc paths that start with a given prefix, and thus loop - * on a qrc directory. - * - * Qrc files also support languages, those are mapped to a prefix of the qrc path. - * For example the french /image/bla.png (lang=fr) will have the path "fr/image/bla.png". - * The empty language represent the default resource. - * Languages are looked up using the locale uiLanguages() property - * - * For a single qrc a given path maps to a single file, but when one has multiple - * (platform specific exclusive) qrc files, then multiple files match, so QStringList are used. - * - * Especially the collect* functions are thought as low level interface. - */ + class QrcParserPrivate { Q_DECLARE_TR_FUNCTIONS(QmlJS::QrcParser) @@ -109,8 +89,44 @@ private: }; } // namespace Internal -/*! \brief normalizes the path to a file in a qrc resource by dropping the "qrc:/" or ":" and - * any extra slashes at the beginning +/*! + \class Utils::QrcParser + \inmodule QtCreator + \brief The QrcParser class parses one or more QRC files and keeps their + content cached. + + A \l{The Qt Resource System}{Qt resource collection (QRC)} contains files + read from the file system but organized in a possibly different way. + To easily describe that with a simple structure, we use a map from QRC paths + to the paths in the filesystem. + By using a map, we can easily find all QRC paths that start with a given + prefix, and thus loop on a QRC directory. + + QRC files also support languages, which are mapped to a prefix of the QRC + path. For example, the French /image/bla.png (lang=fr) will have the path + \c {fr/image/bla.png}. The empty language represents the default resource. + Languages are looked up using the locale uiLanguages() property + + For a single QRC, a given path maps to a single file, but when one has + multiple (platform-specific and mutually exclusive) QRC files, multiple + files match, so QStringList are used. + + Especially, the \c collect* functions are thought of as low level interface. + */ + +/*! + \typedef QrcParser::Ptr + Represents pointers. + */ + +/*! + \typedef QrcParser::ConstPtr + Represents constant pointers. +*/ + +/*! + Normalizes the \a path to a file in a QRC resource by dropping the \c qrc:/ + or \c : and any extra slashes in the beginning. */ QString QrcParser::normalizedQrcFilePath(const QString &path) { QString normPath = path; @@ -128,8 +144,10 @@ QString QrcParser::normalizedQrcFilePath(const QString &path) { return normPath; } -/*! \brief normalizes the path to a directory in a qrc resource by dropping the "qrc:/" or ":" and - * any extra slashes at the beginning, and ensuring it ends with a slash +/*! + Returns the path to a directory normalized to \a path in a QRC resource by + dropping the \c qrc:/ or \c : and any extra slashes at the beginning, and + by ensuring that the path ends with a slash */ QString QrcParser::normalizedQrcDirectoryPath(const QString &path) { QString normPath = normalizedQrcFilePath(path); @@ -138,6 +156,9 @@ QString QrcParser::normalizedQrcDirectoryPath(const QString &path) { return normPath; } +/*! + Returns the QRC directory path for \a file. +*/ QString QrcParser::qrcDirectoryPathForQrcFilePath(const QString &file) { return file.left(file.lastIndexOf(QLatin1Char('/'))); @@ -148,45 +169,61 @@ QrcParser::QrcParser() d = new Internal::QrcParserPrivate(this); } +/*! + Destructs the QRC parser. +*/ QrcParser::~QrcParser() { delete d; } +/*! + Returns the \a contents of the file at \a path. +*/ bool QrcParser::parseFile(const QString &path, const QString &contents) { return d->parseFile(path, contents); } -/*! \brief returns fs path of the first (active) file at the given qrc path +/*! + Returns the file system path of the first (active) file at the given QRC + \a path and \a locale. */ QString QrcParser::firstFileAtPath(const QString &path, const QLocale &locale) const { return d->firstFileAtPath(path, locale); } -/*! \brief adds al the fs paths for the given qrc path to *res - * If locale is null all possible files are added, otherwise just the first match - * using that locale. +/*! + Adds the file system paths for the given QRC \a path to \a res. + + If \a locale is null, all possible files are added. Otherwise, just + the first one that matches the locale is added. */ void QrcParser::collectFilesAtPath(const QString &path, QStringList *res, const QLocale *locale) const { d->collectFilesAtPath(path, res, locale); } -/*! \brief returns true if the given path is a non empty directory +/*! + Returns \c true if \a path is a non-empty directory and matches \a locale. + */ bool QrcParser::hasDirAtPath(const QString &path, const QLocale *locale) const { return d->hasDirAtPath(path, locale); } -/*! \brief adds the directory contents of the given qrc path to res - * - * adds the qrcFileName => fs paths associations contained in the given qrc path - * to res. If addDirs is true directories are also added. - * If locale is null all possible files are added, otherwise just the first match - * using that locale. +/*! + Adds the directory contents of the given QRC \a path to \a res if \a addDirs + is set to \c true. + + Adds the QRC filename to file system path associations contained in the + given \a path to \a res. If addDirs() is \c true, directories are also + added. + + If \a locale is null, all possible files are added. Otherwise, just the + first file with a matching the locale is added. */ void QrcParser::collectFilesInPath(const QString &path, QMap *res, bool addDirs, const QLocale *locale) const @@ -194,33 +231,47 @@ void QrcParser::collectFilesInPath(const QString &path, QMapcollectFilesInPath(path, res, addDirs, locale); } +/*! + Adds the resource files from the QRC file \a sourceFile to \a res. + + If \a locale is null, all possible files are added. Otherwise, just + the first file with a matching the locale is added. + */ void QrcParser::collectResourceFilesForSourceFile(const QString &sourceFile, QStringList *res, const QLocale *locale) const { d->collectResourceFilesForSourceFile(sourceFile, res, locale); } -/*! \brief returns the errors found while parsing +/*! + Returns the errors found while parsing. */ QStringList QrcParser::errorMessages() const { return d->errorMessages(); } -/*! \brief returns all languages used in this qrc resource +/*! + Returns all languages used in this QRC. */ QStringList QrcParser::languages() const { return d->languages(); } -/*! \brief if the contents are valid +/*! + Indicates whether the QRC contents are valid. + + Returns an error if the QRC is empty. */ bool QrcParser::isValid() const { return errorMessages().isEmpty(); } +/*! + Returns the \a contents of the QRC file at \a path. +*/ QrcParser::Ptr QrcParser::parseQrcFile(const QString &path, const QString &contents) { Ptr res(new QrcParser); @@ -231,36 +282,62 @@ QrcParser::Ptr QrcParser::parseQrcFile(const QString &path, const QString &conte // ---------------- +/*! + \class Utils::QrcCache + \inmodule QtCreator + \brief The QrcCache class caches the contents of parsed QRC files. + + \sa Utils::QrcParser +*/ + QrcCache::QrcCache() { d = new Internal::QrcCachePrivate(this); } +/*! + \internal +*/ QrcCache::~QrcCache() { delete d; } +/*! + Returns the \a contents of a file at \a path. +*/ QrcParser::ConstPtr QrcCache::addPath(const QString &path, const QString &contents) { return d->addPath(path, contents); } +/*! + Removes \a path from the cache. +*/ void QrcCache::removePath(const QString &path) { d->removePath(path); } +/*! + Returns updates to the \a contents of a file at \a path. +*/ QrcParser::ConstPtr QrcCache::updatePath(const QString &path, const QString &contents) { return d->updatePath(path, contents); } +/*! + Returns the parsed \a path. +*/ QrcParser::ConstPtr QrcCache::parsedPath(const QString &path) { return d->parsedPath(path); } +/*! + Clears the contents of the cache. +*/ void QrcCache::clear() { d->clear(); -- cgit v1.2.1