summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMartin Smith <msmith@trolltech.com>2009-12-04 14:01:49 (GMT)
committerMartin Smith <msmith@trolltech.com>2009-12-04 14:01:49 (GMT)
commit77f274672480e5980d9f42e4fd94c9770279543b (patch)
tree159b4e4238d8e9ec6d5c056db4c8090a164850cb
parent271936b063fb261293e3f77f7a2273e3a4dbb5d6 (diff)
downloadQt-77f274672480e5980d9f42e4fd94c9770279543b.zip
Qt-77f274672480e5980d9f42e4fd94c9770279543b.tar.gz
Qt-77f274672480e5980d9f42e4fd94c9770279543b.tar.bz2
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
-rw-r--r--tools/qdoc3/config.cpp12
-rw-r--r--tools/qdoc3/config.h1
-rw-r--r--tools/qdoc3/cppcodeparser.cpp67
-rw-r--r--tools/qdoc3/cppcodeparser.h1
-rw-r--r--tools/qdoc3/generator.cpp94
-rw-r--r--tools/qdoc3/generator.h4
-rw-r--r--tools/qdoc3/node.cpp12
-rw-r--r--tools/qdoc3/node.h1
-rw-r--r--tools/qdoc3/test/qt-build-docs.qdocconf1
-rw-r--r--tools/qdoc3/test/qt.qdocconf1
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 \