doc: Example page now lists images used by the example

It just links to an empty page at the moment, i.e., it doesn't
load the images. But I will add that.

Task-number: QTBUG-4484

10 files changed, 168 insertions, 26 deletions

diff --git a/tools/qdoc3/config.cpp b/tools/qdoc3/config.cpp
index 0fc3606..1a4e46e 100644
--- a/tools/qdoc3/config.cpp
+++ b/tools/qdoc3/config.cpp
@@ -399,6 +399,13 @@ QStringList Config::getAllFiles(const QString &filesVar,
 }
 
 /*!
+  \a fileName is the path of the file to find.
+
+  \a files and \a dirs are the lists where we must find the
+  components of \a fileName.
+  
+  \a location is used for obtaining the file and line numbers
+  for report qdoc errors.
  */
 QString Config::findFile(const Location& location,
                          const QStringList& files,
@@ -527,6 +534,11 @@ QString Config::findFile(const Location& location,
 }
 
 /*!
+  Copies the \a sourceFilePath to the file name constructed by
+  concatenating \a targetDirPath and \a userFriendlySourceFilePath.
+  \a location is for identifying the file and line number where
+  a qdoc error occurred. The constructed output file name is
+  returned.
  */
 QString Config::copyFile(const Location& location,
                          const QString& sourceFilePath,
diff --git a/tools/qdoc3/config.h b/tools/qdoc3/config.h
index 725129a..33e5739 100644
--- a/tools/qdoc3/config.h
+++ b/tools/qdoc3/config.h
@@ -161,6 +161,7 @@ class Config
 #define CONFIG_VERSIONSYM               "versionsym"
 
 #define CONFIG_FILEEXTENSIONS           "fileextensions"
+#define CONFIG_IMAGEEXTENSIONS          "imageextensions"
 
 #ifdef QDOC_QML
 #define CONFIG_QMLONLY                  "qmlonly"
diff --git a/tools/qdoc3/cppcodeparser.cpp b/tools/qdoc3/cppcodeparser.cpp
index ce71e51..41a2456 100644
--- a/tools/qdoc3/cppcodeparser.cpp
+++ b/tools/qdoc3/cppcodeparser.cpp
@@ -197,8 +197,14 @@ CppCodeParser::CppCodeParser()
  */
 CppCodeParser::~CppCodeParser()
 {
+    // nothing.
 }
 
+/*!
+  The constructor initializes a map of special node types
+  for identifying important nodes. And it initializes
+  some filters for identifying certain kinds of files.
+ */
 void CppCodeParser::initializeParser(const Config &config)
 {
     CodeParser::initializeParser(config);
@@ -220,24 +226,46 @@ void CppCodeParser::initializeParser(const Config &config)
         exampleNameFilter = exampleFilePatterns.join(" ");
     else
         exampleNameFilter = "*.cpp *.h *.js *.xq *.svg *.xml *.ui";
+
+    QStringList exampleImagePatterns = config.getStringList(
+        CONFIG_EXAMPLES + Config::dot + CONFIG_IMAGEEXTENSIONS);
+
+    if (!exampleImagePatterns.isEmpty())
+        exampleImageFilter = exampleImagePatterns.join(" ");
+    else
+        exampleImageFilter = "*.png";
 }
 
+/*!
+  Clear the map of common node types and call
+  the same function in the base class.
+ */
 void CppCodeParser::terminateParser()
 {
     nodeTypeMap.clear();
     CodeParser::terminateParser();
 }
 
+/*!
+  Returns "Cpp".
+ */
 QString CppCodeParser::language()
 {
     return "Cpp";
 }
 
+/*!
+  Returns a list of extensions for header files.
+ */
 QString CppCodeParser::headerFileNameFilter()
 {
     return "*.ch *.h *.h++ *.hh *.hpp *.hxx";
 }
 
+/*!
+  Returns a list of extensions for source files, i.e. not
+  header files.
+ */
 QString CppCodeParser::sourceFileNameFilter()
 {
     return "*.c++ *.cc *.cpp *.cxx";
@@ -299,6 +327,12 @@ void CppCodeParser::parseSourceFile(const Location& location,
     fclose(in);
 }
 
+/*!
+  This is called after all the header files have been parsed.
+  I think the most important thing it does is resolve class
+  inheritance links in the tree. But it also initializes a
+  bunch of stuff.
+ */
 void CppCodeParser::doneParsingHeaderFiles(Tree *tree)
 {
     tree->resolveInheritance();
@@ -345,6 +379,12 @@ void CppCodeParser::doneParsingHeaderFiles(Tree *tree)
     mutableAssociativeIteratorClasses.clear();
 }
 
+/*!
+  This is called after all the source files (i.e., not the
+  header files) have been parsed. It traverses the tree to
+  resolve property links, normalize overload signatures, and
+  do other housekeeping of the tree.
+ */
 void CppCodeParser::doneParsingSourceFiles(Tree *tree)
 {
     tree->root()->makeUndocumentedChildrenInternal();
@@ -353,6 +393,13 @@ void CppCodeParser::doneParsingSourceFiles(Tree *tree)
     tree->resolveProperties();
 }
 
+/*!
+  This function searches the \a tree to find a FunctionNode
+  for a function with the signature \a synopsis. If the
+  \a relative node is provided, the search begins there. If
+  \a fuzzy is true, base classes are searched. The function
+  node is returned, if found.
+ */
 const FunctionNode *CppCodeParser::findFunctionNode(const QString& synopsis,
                                                     Tree *tree,
                                                     Node *relative,
@@ -2212,6 +2259,7 @@ void CppCodeParser::createExampleFileNodes(FakeNode *fake)
                                         exampleDirs,
                                         proFileName,
                                         userFriendlyFilePath);
+    
     if (fullPath.isEmpty()) {
         QString tmp = proFileName;
         proFileName = examplePath + "/" + "qbuild.pro";
@@ -2231,8 +2279,18 @@ void CppCodeParser::createExampleFileNodes(FakeNode *fake)
     int sizeOfBoringPartOfName = fullPath.size() - proFileName.size();
     fullPath.truncate(fullPath.lastIndexOf('/'));
 
-    QStringList exampleFiles = Config::getFilesHere(fullPath,
-                                                    exampleNameFilter);
+    QStringList exampleFiles = Config::getFilesHere(fullPath,exampleNameFilter);
+    QString imagesPath = fullPath + "/images";
+    QStringList imageFiles = Config::getFilesHere(imagesPath,exampleImageFilter);
+
+#if 0    
+    qDebug() << "examplePath:" << examplePath;
+    qDebug() << " exampleFiles" <<  exampleFiles;
+    qDebug() << "imagesPath:" << imagesPath;
+    qDebug() << "fullPath:" << fullPath;
+    qDebug() << " imageFiles" <<  imageFiles;
+#endif    
+
     if (!exampleFiles.isEmpty()) {
         // move main.cpp and to the end, if it exists
         QString mainCpp;
@@ -2259,6 +2317,11 @@ void CppCodeParser::createExampleFileNodes(FakeNode *fake)
         (void) new FakeNode(fake,
                             exampleFile.mid(sizeOfBoringPartOfName),
                             Node::File);
+    foreach (const QString &imageFile, imageFiles) {
+        FakeNode* newFake = new FakeNode(fake,
+                                         imageFile.mid(sizeOfBoringPartOfName),
+                                         Node::Image);
+    }
 }
 
 QT_END_NAMESPACE
diff --git a/tools/qdoc3/cppcodeparser.h b/tools/qdoc3/cppcodeparser.h
index e2e9d55..fff5bd9 100644
--- a/tools/qdoc3/cppcodeparser.h
+++ b/tools/qdoc3/cppcodeparser.h
@@ -185,6 +185,7 @@ class CppCodeParser : public CodeParser
     static QStringList exampleFiles;
     static QStringList exampleDirs;
     QString exampleNameFilter;
+    QString exampleImageFilter;
 };
 
 QT_END_NAMESPACE
diff --git a/tools/qdoc3/generator.cpp b/tools/qdoc3/generator.cpp
index f7569ce..9389268 100644
--- a/tools/qdoc3/generator.cpp
+++ b/tools/qdoc3/generator.cpp
@@ -138,14 +138,15 @@ void Generator::initialize(const Config &config)
     while (g != generators.end()) {
         if (outputFormats.contains((*g)->format())) {
             (*g)->initializeGenerator(config);
-            QStringList extraImages = config.getStringList(CONFIG_EXTRAIMAGES +
-                                                           Config::dot +
-                                                           (*g)->format());
+            QStringList extraImages =
+                config.getStringList(CONFIG_EXTRAIMAGES+Config::dot+(*g)->format());
             QStringList::ConstIterator e = extraImages.begin();
             while (e != extraImages.end()) {
                 QString userFriendlyFilePath;
                 QString filePath = Config::findFile(config.lastLocation(),
-                                                    imageFiles, imageDirs, *e,
+                                                    imageFiles,
+                                                    imageDirs,
+                                                    *e,
                                                     imgFileExts[(*g)->format()],
                                                     userFriendlyFilePath);
                 if (!filePath.isEmpty())
@@ -529,33 +530,80 @@ void Generator::generateInheritedBy(const ClassNode *classe,
     }
 }
 
-void Generator::generateExampleFiles(const FakeNode *fake, CodeMarker *marker)
+void Generator::generateFileList(const FakeNode* fake,
+                                 CodeMarker* marker,
+                                 Node::SubType subtype,
+                                 const QString& tag)
 {
-    if (fake->childNodes().isEmpty())
-        return;
-
+    int count = 0;
+    Text text;
     OpenedList openedList(OpenedList::Bullet);
 
-    Text text;
-    text << Atom::ParaLeft << "Files:" << Atom::ParaRight
+    text << Atom::ParaLeft << tag << Atom::ParaRight
          << Atom(Atom::ListLeft, openedList.styleString());
-    foreach (const Node *child, fake->childNodes()) {
-        QString exampleFile = child->name();
-        openedList.next();
-        text << Atom(Atom::ListItemNumber, openedList.numberString())
-             << Atom(Atom::ListItemLeft, openedList.styleString())
-             << Atom::ParaLeft
-             << Atom(Atom::Link, exampleFile)
-             << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
-             << exampleFile
-             << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
-             << Atom::ParaRight
-             << Atom(Atom::ListItemRight, openedList.styleString());
+
+    foreach (const Node* child, fake->childNodes()) {
+        if (child->subType() == subtype) {
+            ++count;
+            QString file = child->name();
+
+            if (file == "network/qftp/images/dir.png")
+                qDebug() << "FILE:" << file;
+
+            openedList.next();
+            text << Atom(Atom::ListItemNumber, openedList.numberString())
+                 << Atom(Atom::ListItemLeft, openedList.styleString())
+                 << Atom::ParaLeft
+                 << Atom(Atom::Link, file)
+                 << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK)
+                 << file
+                 << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK)
+                 << Atom::ParaRight
+                 << Atom(Atom::ListItemRight, openedList.styleString());
+        }
     }
     text << Atom(Atom::ListRight, openedList.styleString());
-    generateText(text, fake, marker);
+    if (count > 0)
+        generateText(text, fake, marker);
 }
 
+void Generator::generateExampleFiles(const FakeNode *fake, CodeMarker *marker)
+{
+    if (fake->childNodes().isEmpty())
+        return;
+    generateFileList(fake, marker, Node::File, QString("Files:"));
+    generateFileList(fake, marker, Node::Image, QString("Images:"));
+}
+
+#if 0
+    QList<Generator *>::ConstIterator g = generators.begin();
+    while (g != generators.end()) {
+        if (outputFormats.contains((*g)->format())) {
+            (*g)->initializeGenerator(config);
+            QStringList extraImages =
+                config.getStringList(CONFIG_EXTRAIMAGES+Config::dot+(*g)->format());
+            QStringList::ConstIterator e = extraImages.begin();
+            while (e != extraImages.end()) {
+                QString userFriendlyFilePath;
+                QString filePath = Config::findFile(config.lastLocation(),
+                                                    imageFiles,
+                                                    imageDirs,
+                                                    *e,
+                                                    imgFileExts[(*g)->format()],
+                                                    userFriendlyFilePath);
+                if (!filePath.isEmpty())
+                    Config::copyFile(config.lastLocation(),
+                                     filePath,
+                                     userFriendlyFilePath,
+                                     (*g)->outputDir() +
+                                     "/images");
+                ++e;
+            }
+        }
+        ++g;
+    }
+#endif
+
 void Generator::generateModuleWarning(const ClassNode *classe,
                                       CodeMarker *marker)
 {
diff --git a/tools/qdoc3/generator.h b/tools/qdoc3/generator.h
index 0258534..7667789 100644
--- a/tools/qdoc3/generator.h
+++ b/tools/qdoc3/generator.h
@@ -119,6 +119,10 @@ class Generator
                                  CodeMarker *marker, 
                                  bool generate,
                                  int& numGeneratedAtoms);
+    void generateFileList(const FakeNode* fake,
+                          CodeMarker* marker,
+                          Node::SubType subtype,
+                          const QString& tag);
     void generateExampleFiles(const FakeNode *fake, CodeMarker *marker);
     void generateModuleWarning(const ClassNode *classe, CodeMarker *marker);
 
diff --git a/tools/qdoc3/node.cpp b/tools/qdoc3/node.cpp
index 373002c..b855823 100644
--- a/tools/qdoc3/node.cpp
+++ b/tools/qdoc3/node.cpp
@@ -767,6 +767,9 @@ FakeNode::FakeNode(InnerNode *parent, const QString& name, SubType subtype)
 }
 
 /*!
+  Returns the fake node's full title, which is usually
+  just title(), but for some SubType values is different
+  from title()
  */
 QString FakeNode::fullTitle() const
 {
@@ -776,6 +779,12 @@ QString FakeNode::fullTitle() const
         else
             return title();
     }
+    else if (sub == Image) {
+        if (title().isEmpty())
+            return name().mid(name().lastIndexOf('/') + 1) + " Image File";
+        else
+            return title();
+    }
     else if (sub == HeaderFile) {
         if (title().isEmpty())
             return name();
@@ -788,13 +797,14 @@ QString FakeNode::fullTitle() const
 }
 
 /*!
+  Returns the subtitle.
  */
 QString FakeNode::subTitle() const
 {
     if (!stle.isEmpty())
         return stle;
 
-    if (sub == File) {
+    if ((sub == File) || (sub == Image)) {
         if (title().isEmpty() && name().contains("/"))
             return name();
     }
diff --git a/tools/qdoc3/node.h b/tools/qdoc3/node.h
index dbdc174..223f528 100644
--- a/tools/qdoc3/node.h
+++ b/tools/qdoc3/node.h
@@ -89,6 +89,7 @@ class Node
         Example, 
         HeaderFile, 
         File,
+        Image,
         Group,
         Module,
         Page,
diff --git a/tools/qdoc3/test/qt-build-docs.qdocconf b/tools/qdoc3/test/qt-build-docs.qdocconf
index d1733e5..09a4e4c 100644
--- a/tools/qdoc3/test/qt-build-docs.qdocconf
+++ b/tools/qdoc3/test/qt-build-docs.qdocconf
@@ -97,6 +97,7 @@ excludedirs             = $QT_SOURCE_TREE/src/3rdparty/clucene \
 
 sources.fileextensions  = "*.cpp *.qdoc *.mm"
 examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp"
+examples.imageextensions = "*.png"
 
 exampledirs             = $QT_SOURCE_TREE/doc/src \
                           $QT_SOURCE_TREE/examples \
diff --git a/tools/qdoc3/test/qt.qdocconf b/tools/qdoc3/test/qt.qdocconf
index d70ef58..58bb2a3 100644
--- a/tools/qdoc3/test/qt.qdocconf
+++ b/tools/qdoc3/test/qt.qdocconf
@@ -100,6 +100,7 @@ excludedirs             = $QTDIR/src/3rdparty/clucene \
 
 sources.fileextensions  = "*.cpp *.qdoc *.mm"
 examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp"
+examples.imageextensions = "*.png"
 
 exampledirs             = $QTDIR/doc/src \
                           $QTDIR/examples \