From 77f274672480e5980d9f42e4fd94c9770279543b Mon Sep 17 00:00:00 2001 From: Martin Smith Date: Fri, 4 Dec 2009 15:01:49 +0100 Subject: 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 --- tools/qdoc3/config.cpp | 12 +++++ tools/qdoc3/config.h | 1 + tools/qdoc3/cppcodeparser.cpp | 67 ++++++++++++++++++++++- tools/qdoc3/cppcodeparser.h | 1 + tools/qdoc3/generator.cpp | 94 +++++++++++++++++++++++++-------- tools/qdoc3/generator.h | 4 ++ tools/qdoc3/node.cpp | 12 ++++- tools/qdoc3/node.h | 1 + tools/qdoc3/test/qt-build-docs.qdocconf | 1 + tools/qdoc3/test/qt.qdocconf | 1 + 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::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 \ -- cgit v0.12