From f74df71c48e5878de8eb44ee107aeed42385eff6 Mon Sep 17 00:00:00 2001
From: Topi Reinio <topi.reinio@qt.io>
Date: Mon, 3 Jul 2017 15:48:50 +0200
Subject: [PATCH] qdoc: Further improve example file listing
Fix a bug where '\generatelist examplefiles' with no second parameter
produced an empty list, instead of listing all files.
Also, no longer restrict the searching of example image files to the
images/ subdirectory. All images under a project directory are now
listed, except those under doc/images.
Minor fixes to related QDoc documentation.
Change-Id: Id4516ba2feb98466a0e893a85f85118e3d21eae2
Reviewed-by: Martin Smith <martin.smith@qt.io>
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
---
src/qdoc/cppcodeparser.cpp | 6 ++++--
src/qdoc/doc/qdoc-manual-topiccmds.qdoc | 16 ++++++++++------
src/qdoc/htmlgenerator.cpp | 7 +++++--
3 files changed, 19 insertions(+), 10 deletions(-)
diff --git a/src/qdoc/cppcodeparser.cpp b/src/qdoc/cppcodeparser.cpp
index a819026d8..7298d1ec2 100644
--- a/src/qdoc/cppcodeparser.cpp
+++ b/src/qdoc/cppcodeparser.cpp
@@ -2651,8 +2651,10 @@ void CppCodeParser::createExampleFileNodes(DocumentNode *dn)
fullPath.truncate(fullPath.lastIndexOf('/'));
QStringList exampleFiles = Config::getFilesHere(fullPath, exampleNameFilter, Location(), excludeDirs, excludeFiles);
- QString imagesPath = fullPath + "/images";
- QStringList imageFiles = Config::getFilesHere(imagesPath, exampleImageFilter, Location(), excludeDirs, excludeFiles);
+ // Search for all image files under the example project, excluding doc/images directory.
+ QSet<QString> excludeDocDirs(excludeDirs);
+ excludeDocDirs.insert(QDir(fullPath).canonicalPath() + "/doc/images");
+ QStringList imageFiles = Config::getFilesHere(fullPath, exampleImageFilter, Location(), excludeDocDirs, excludeFiles);
if (!exampleFiles.isEmpty()) {
// move main.cpp and to the end, if it exists
QString mainCpp;
diff --git a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
index 9fd97457d..53fe85684 100644
--- a/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
+++ b/src/qdoc/doc/qdoc-manual-topiccmds.qdoc
@@ -360,13 +360,13 @@
\section1 \\example
The \\example command is for documenting an example. The argument
- is the example's path relative to omne of the paths listed in the
+ is the example's path relative to one of the paths listed in the
\l {exampledirs-variable} {exampledirs} variable in the QDoc
configuration file.
- The documentation page will be output to \c {path-to-example}.html.
- QDoc will add a list of all the example's source files at the top
- of the page.
+ The documentation page will be output to \c {modulename-path-to-example}.html.
+ QDoc will add a list of all the example's source and images files at the end
+ of the page, unless \l {noautolist-command}{\\noautolist} command is used.
For example, if \l {exampledirs-variable} {exampledirs} contains
\c $QTDIR/examples/widgets/imageviewer, then
@@ -391,6 +391,9 @@
<center><h1>Image Viewer Example</h1></center>
\endraw
+ The example shows how to combine QLabel and QScrollArea
+ to display an image.
+
Files:
\list
\li \l{http://doc.qt.io/qt-5/qtwidgets-widgets-imageviewer-imageviewer-cpp.html}
@@ -401,12 +404,13 @@
{widgets/imageviewer/main.cpp}
\endlist
- The example shows how to combine QLabel and QScrollArea
- to display an image.
...
\endquotation
+ \b {See also:} \l {generatelist-command}{\\generatelist examplefiles},
+ \l {noautolist-command}{\\noautolist}
+
\target externalpage-command
\section1 \\externalpage
diff --git a/src/qdoc/htmlgenerator.cpp b/src/qdoc/htmlgenerator.cpp
index 10199d7df..a0f8eacde 100644
--- a/src/qdoc/htmlgenerator.cpp
+++ b/src/qdoc/htmlgenerator.cpp
@@ -713,8 +713,11 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
atom->string().startsWith("exampleimages")) {
if (relative->isExample()) {
Node::DocSubtype subType = (atom->string().mid(7,5) == "image") ? Node::Image : Node::File;
- generateFileList(static_cast<const DocumentNode*>(relative), marker, subType,
- atom->string().mid(atom->string().indexOf(" ")).trimmed());
+ QString regExp;
+ int secondArg = atom->string().indexOf(" ");
+ if (secondArg != -1)
+ regExp = atom->string().mid(++secondArg);
+ generateFileList(static_cast<const DocumentNode*>(relative), marker, subType, regExp);
}
else
relative->location().warning(QString("'\\generatelist \1' can only be used with '\\example' topic command").arg(atom->string()));
--
GitLab