qdoc: Adding a debug function

qdoc segfaults for one user, when he runs
the release version of qdoc but not the debug
version. This change adds a -debug option to
the qdoc command line options. If set, qdoc
will print debug messages at useful milestones
so we can see where it is when it goes into
the weeds.

Change-Id: I0e826e74399eaf50091817c68c775d02c6b615d2
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

4 files changed, 41 insertions, 0 deletions

diff --git a/src/tools/qdoc/generator.cpp b/src/tools/qdoc/generator.cpp
index 830ac06908..a349bf5405 100644
--- a/src/tools/qdoc/generator.cpp
+++ b/src/tools/qdoc/generator.cpp
@@ -94,6 +94,24 @@ QString Generator::sinceTitles[] =
 };
 QStringList Generator::styleDirs;
 QStringList Generator::styleFiles;
+bool Generator::debugging_ = false;
+
+void Generator::setDebugSegfaultFlag(bool b)
+{
+    if (b)
+        qDebug() << "DEBUG: Setting debug flag.";
+    else
+        qDebug() << "DEBUG: Clearing debug flag.";
+    debugging_ = b;
+}
+
+/*!
+  Prints \a message as an aid to debugging the release version.
+ */
+void Generator::debugSegfault(const QString& message)
+{
+    qDebug() << "DEBUG:" << message;
+}
 
 /*!
   Constructs the generator base class. Prepends the newly
@@ -244,6 +262,7 @@ void Generator::beginSubPage(const InnerNode* node, const QString& fileName)
     if (!node->outputSubdirectory().isEmpty())
         path += node->outputSubdirectory() + QLatin1Char('/');
     path += fileName;
+    Generator::debugSegfault("Writing: " + path);
     outFileNames.insert(fileName,fileName);
     QFile* outFile = new QFile(path);
     if (!outFile->open(QFile::WriteOnly))
diff --git a/src/tools/qdoc/generator.h b/src/tools/qdoc/generator.h
index 344112e956..56e0d0aa3e 100644
--- a/src/tools/qdoc/generator.h
+++ b/src/tools/qdoc/generator.h
@@ -86,6 +86,9 @@ public:
     static void terminate();
     static void writeOutFileNames();
     static void augmentImageDirs(QSet<QString>& moreImageDirs);
+    static void debugSegfault(const QString& message);
+    static void setDebugSegfaultFlag(bool b);
+    static bool debugging() { return debugging_; }
 
 protected:
     virtual void beginSubPage(const InnerNode* node, const QString& fileName);
@@ -187,6 +190,7 @@ private:
     static QStringList scriptFiles;
     static QStringList styleDirs;
     static QStringList styleFiles;
+    static bool debugging_;
 
     void appendFullName(Text& text,
                         const Node *apparentNode,
diff --git a/src/tools/qdoc/htmlgenerator.cpp b/src/tools/qdoc/htmlgenerator.cpp
index cb4bebb67a..c3cf38b3c3 100644
--- a/src/tools/qdoc/htmlgenerator.cpp
+++ b/src/tools/qdoc/htmlgenerator.cpp
@@ -268,6 +268,9 @@ int HtmlGenerator::generateAtom(const Atom *atom, const Node *relative, CodeMark
     int skipAhead = 0;
     static bool in_para = false;
 
+    if (Generator::debugging()) {
+        atom->dump();
+    }
     switch (atom->type()) {
     case Atom::AbstractLeft:
         if (relative)
diff --git a/src/tools/qdoc/main.cpp b/src/tools/qdoc/main.cpp
index ea42b3f4f3..de28fbf5cc 100644
--- a/src/tools/qdoc/main.cpp
+++ b/src/tools/qdoc/main.cpp
@@ -328,18 +328,21 @@ static void processQdocconfFile(const QString &fileName)
     QStringList excludedDirsList;
     QStringList excludedFilesList;
 
+    Generator::debugSegfault("Reading excludedirs");
     excludedDirsList = config.getCanonicalRelativePathList(CONFIG_EXCLUDEDIRS);
     foreach (const QString &excludeDir, excludedDirsList) {
         QString p = QDir::fromNativeSeparators(excludeDir);
         excludedDirs.insert(p);
     }
 
+    Generator::debugSegfault("Reading excludefiles");
     excludedFilesList = config.getCleanPathList(CONFIG_EXCLUDEFILES);
     foreach (const QString& excludeFile, excludedFilesList) {
         QString p = QDir::fromNativeSeparators(excludeFile);
         excludedFiles.insert(p);
     }
 
+    Generator::debugSegfault("Reading headerdirs");
     headerList = config.getAllFiles(CONFIG_HEADERS,CONFIG_HEADERDIRS,excludedDirs,excludedFiles);
     QMap<QString,QString> headers;
     QMultiMap<QString,QString> headerFileNames;
@@ -349,6 +352,7 @@ static void processQdocconfFile(const QString &fileName)
         headerFileNames.insert(t,t);
     }
 
+    Generator::debugSegfault("Reading sourcedirs");
     sourceList = config.getAllFiles(CONFIG_SOURCES,CONFIG_SOURCEDIRS,excludedDirs,excludedFiles);
     QMap<QString,QString> sources;
     QMultiMap<QString,QString> sourceFileNames;
@@ -361,6 +365,7 @@ static void processQdocconfFile(const QString &fileName)
       Find all the qdoc files in the example dirs, and add
       them to the source files to be parsed.
      */
+    Generator::debugSegfault("Reading exampledirs");
     QStringList exampleQdocList = config.getExampleQdocFiles(excludedDirs, excludedFiles);
     for (int i=0; i<exampleQdocList.size(); ++i) {
         if (!sources.contains(exampleQdocList[i])) {
@@ -370,6 +375,7 @@ static void processQdocconfFile(const QString &fileName)
         }
     }
 
+    Generator::debugSegfault("Adding doc/image dirs found in exampledirs to imagedirs");
     QSet<QString> exampleImageDirs;
     QStringList exampleImageList = config.getExampleImageFiles(excludedDirs, excludedFiles);
     for (int i=0; i<exampleImageList.size(); ++i) {
@@ -388,6 +394,7 @@ static void processQdocconfFile(const QString &fileName)
      */
     QSet<CodeParser *> usedParsers;
 
+    Generator::debugSegfault("Parsing header files");
     int parsed = 0;
     QMap<QString,QString>::ConstIterator h = headers.constBegin();
     while (h != headers.constEnd()) {
@@ -409,6 +416,7 @@ static void processQdocconfFile(const QString &fileName)
       add it to the big tree.
      */
     parsed = 0;
+    Generator::debugSegfault("Parsing source files");
     QMap<QString,QString>::ConstIterator s = sources.constBegin();
     while (s != sources.constEnd()) {
         CodeParser *codeParser = CodeParser::parserForSourceFile(s.key());
@@ -428,6 +436,7 @@ static void processQdocconfFile(const QString &fileName)
       source files. Resolve all the class names, function names,
       targets, URLs, links, and other stuff that needs resolving.
      */
+    Generator::debugSegfault("Resolving stuff prior to generating docs");
     qdb->resolveIssues();
 
     /*
@@ -436,6 +445,7 @@ static void processQdocconfFile(const QString &fileName)
       documentation output. More than one output format can be
       requested. The tree is traversed for each one.
      */
+    Generator::debugSegfault("Generating docs");
     QSet<QString>::ConstIterator of = outputFormats.constBegin();
     while (of != outputFormats.constEnd()) {
         Generator* generator = Generator::generatorForFormat(*of);
@@ -447,6 +457,7 @@ static void processQdocconfFile(const QString &fileName)
 
 
     //Generator::writeOutFileNames();
+    Generator::debugSegfault("Shutting down qdoc");
 
     QDocDatabase::qdocDB()->setVersion(QString());
     Generator::terminate();
@@ -467,6 +478,7 @@ static void processQdocconfFile(const QString &fileName)
 #ifdef DEBUG_SHUTDOWN_CRASH
     qDebug() << "main(): qdoc database deleted";
 #endif
+    Generator::debugSegfault("qdoc finished!");
 }
 
 QT_END_NAMESPACE
@@ -560,6 +572,9 @@ int main(int argc, char **argv)
             Config::overrideOutputFormats.insert(argv[i]);
             i++;
         }
+        else if (opt == "-debug") {
+            Generator::setDebugSegfaultFlag(true);
+        }
         else {
             qdocFiles.append(opt);
         }