diff options
author | Oswald Buddenhagen <oswald.buddenhagen@digia.com> | 2013-03-07 19:22:06 +0100 |
---|---|---|
committer | Simon Hausmann <simon.hausmann@theqtcompany.com> | 2015-10-22 19:40:09 +0000 |
commit | f343989852b555fd960f5eaae51ece1423ba4373 (patch) | |
tree | e1333d22519c72f0fa4759f9a5dc010bf8969bbe /src | |
parent | a903ddd8dc806b51c21c84965611880a25037562 (diff) |
qdoc is moving back to qttools
Change-Id: Icb5abd32a1cbc3e8d876341c877e8d2a963c0e25
Reviewed-by: Frederik Gladhorn <frederik.gladhorn@theqtcompany.com>
Reviewed-by: Topi Reiniƶ <topi.reinio@digia.com>
Diffstat (limited to 'src')
125 files changed, 1 insertions, 65530 deletions
diff --git a/src/src.pro b/src/src.pro index 07ace99144..a970391382 100644 --- a/src/src.pro +++ b/src/src.pro @@ -28,12 +28,6 @@ src_tools_uic.CONFIG = host_build force_bootstrap: src_tools_uic.depends = src_tools_bootstrap else: src_tools_uic.depends = src_corelib -src_tools_qdoc.subdir = tools/qdoc -src_tools_qdoc.target = sub-qdoc -src_tools_qdoc.CONFIG = host_build -force_bootstrap: src_tools_qdoc.depends = src_tools_bootstrap -else: src_tools_qdoc.depends = src_corelib src_xml - src_tools_bootstrap_dbus.subdir = tools/bootstrap-dbus src_tools_bootstrap_dbus.target = sub-bootstrap_dbus src_tools_bootstrap_dbus.depends = src_tools_bootstrap @@ -182,7 +176,7 @@ contains(QT_CONFIG, concurrent):SUBDIRS += src_concurrent } } } -SUBDIRS += src_plugins src_tools_qdoc +SUBDIRS += src_plugins nacl: SUBDIRS -= src_network src_testlib diff --git a/src/tools/qdoc/TODO.txt b/src/tools/qdoc/TODO.txt deleted file mode 100644 index 9bf4a2864f..0000000000 --- a/src/tools/qdoc/TODO.txt +++ /dev/null @@ -1,87 +0,0 @@ - * fix QWSPointerCalibrationData::devPoints and qwsServer - * Fix QMenu::addAction(QAction *) overload, "using" etc. - * fix space between two tables using <p></p> - * qpixmap-qt3.html; remove 8 public functions inherited from QPaintDevice - * \variable array - * Added support for parameterless macros (e.g. \macro Q_OBJECT). - * Made qdoc stricter regarding the data types (e.g. can't use \enum to document a typedef). - * Parse QT_MODULE() macro and generate proper warnings for the various editions. - * Fix parsing of \image following \value (e.g. qt.html). - * Don't turn X11 and similar names into links. - * Added automatic links from getters to setters and vice versa. - * Support \module and show which module each class is from. - * Fix occasional crash caused by misuse of const_cast(). - * Provide clearer error messages when resolves fail. - - - - -CHECK: - - * Identify editions - * Automatic \sa getter setter - * \macro Q_OBJECT - -MUST HAVES: - - * resolve [gs]etters for \sa using base class - - * fix \overload when one is a signal and the other a normal function - * use "project" for .dcf files - * functions.html: include the types from QtGlobal as well as the functions (whatever that means) - - * nice template function/class syntax - * spellchecker: built-in vs. builtin - - * verbose mode for functions that don't exist - * No links to Porting Guide sections (e.g. QStringList) - * link toggled(bool) - * autolink foo(1) - * handle using correctly - * QObject "reentrant" list: duplicates - * operator<< \overload - * \compat \overload - * qWarning() link - * operator<<() autolink - - * get rid of spurious 'global' functions - * Make automatic links in code work - - * Fix encoding bug (see Important email from Simon Hausmann) - * Make links to QFoo::bar().baz() work - * Fix automatic links in \sectionX (e.g. qt4-getting-started.html) - * Provide a "List of all properties" page. - - * expand QObjectList -> QList<QObject *> - * warning for unnamed parameters in property access functions - * \center...\endcenter - -LINKS: - - * explanation following nonstandard wording warning - - * omit \overload in operator<< and operator>> - * make operator-() unary and binary independent functions (no \overload) - * fix \overload - * fix \legalese - * remove warning for undocumented enum item like QLocale::LastLanguage - * improve the \a warnings for overloads; if one overload documents a para, fine - - * implement \sidebar - - * implement \legalesefile - - * show in which module each class is - * list namespaces, list header files - - -NICE FEATURES: - * implement inheritance tree for each class (as a PNG) - * avoid <p>...</p> in table/item cells without relying on horrible kludge - * prevent macros from having same name as commands - * be smart about enum types Foo::Bar vs. Bar when comparing functions - * be smart about const & non-const when comparing functions - -OTHER: - * make qdoc run faster - * make sure \headerfile works even if specified after \relates diff --git a/src/tools/qdoc/atom.cpp b/src/tools/qdoc/atom.cpp deleted file mode 100644 index f50f401c5b..0000000000 --- a/src/tools/qdoc/atom.cpp +++ /dev/null @@ -1,460 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include <qregexp.h> -#include "atom.h" -#include "location.h" -#include "qdocdatabase.h" -#include <stdio.h> -#include <qdebug.h> - -QT_BEGIN_NAMESPACE - -/*! \class Atom - \brief The Atom class is the fundamental unit for representing - documents internally. - - Atoms have a \i type and are completed by a \i string whose - meaning depends on the \i type. For example, the string - \quotation - \i italic text looks nicer than \bold bold text - \endquotation - is represented by the following atoms: - \quotation - (FormattingLeft, ATOM_FORMATTING_ITALIC) - (String, "italic") - (FormattingRight, ATOM_FORMATTING_ITALIC) - (String, " text is more attractive than ") - (FormattingLeft, ATOM_FORMATTING_BOLD) - (String, "bold") - (FormattingRight, ATOM_FORMATTING_BOLD) - (String, " text") - \endquotation - - \also Text -*/ - -/*! \enum Atom::AtomType - - \value AnnotatedList - \value AutoLink - \value BaseName - \value BriefLeft - \value BriefRight - \value C - \value CaptionLeft - \value CaptionRight - \value Code - \value CodeBad - \value CodeNew - \value CodeOld - \value CodeQuoteArgument - \value CodeQuoteCommand - \value DivLeft - \value DivRight - \value EndQmlText - \value FormatElse - \value FormatEndif - \value FormatIf - \value FootnoteLeft - \value FootnoteRight - \value FormattingLeft - \value FormattingRight - \value GeneratedList - \value Image - \value ImageText - \value ImportantNote - \value InlineImage - \value JavaScript - \value EndJavaScript - \value Keyword - \value LineBreak - \value Link - \value LinkNode - \value ListLeft - \value ListItemNumber - \value ListTagLeft - \value ListTagRight - \value ListItemLeft - \value ListItemRight - \value ListRight - \value NavAutoLink - \value NavLink - \value Nop - \value Note - \value ParaLeft - \value ParaRight - \value Qml - \value QmlText - \value QuotationLeft - \value QuotationRight - \value RawString - \value SectionLeft - \value SectionRight - \value SectionHeadingLeft - \value SectionHeadingRight - \value SidebarLeft - \value SidebarRight - \value SinceList - \value String - \value TableLeft - \value TableRight - \value TableHeaderLeft - \value TableHeaderRight - \value TableRowLeft - \value TableRowRight - \value TableItemLeft - \value TableItemRight - \value TableOfContents - \value Target - \value UnhandledFormat - \value UnknownCommand -*/ - -QString Atom::noError_ = QString(); - -static const struct { - const char *english; - int no; -} atms[] = { - { "AnnotatedList", Atom::AnnotatedList }, - { "AutoLink", Atom::AutoLink }, - { "BaseName", Atom::BaseName }, - { "br", Atom::BR}, - { "BriefLeft", Atom::BriefLeft }, - { "BriefRight", Atom::BriefRight }, - { "C", Atom::C }, - { "CaptionLeft", Atom::CaptionLeft }, - { "CaptionRight", Atom::CaptionRight }, - { "Code", Atom::Code }, - { "CodeBad", Atom::CodeBad }, - { "CodeNew", Atom::CodeNew }, - { "CodeOld", Atom::CodeOld }, - { "CodeQuoteArgument", Atom::CodeQuoteArgument }, - { "CodeQuoteCommand", Atom::CodeQuoteCommand }, - { "DivLeft", Atom::DivLeft }, - { "DivRight", Atom::DivRight }, - { "EndQmlText", Atom::EndQmlText }, - { "FootnoteLeft", Atom::FootnoteLeft }, - { "FootnoteRight", Atom::FootnoteRight }, - { "FormatElse", Atom::FormatElse }, - { "FormatEndif", Atom::FormatEndif }, - { "FormatIf", Atom::FormatIf }, - { "FormattingLeft", Atom::FormattingLeft }, - { "FormattingRight", Atom::FormattingRight }, - { "GeneratedList", Atom::GeneratedList }, - { "GuidLink", Atom::GuidLink}, - { "hr", Atom::HR}, - { "Image", Atom::Image }, - { "ImageText", Atom::ImageText }, - { "ImportantLeft", Atom::ImportantLeft }, - { "ImportantRight", Atom::ImportantRight }, - { "InlineImage", Atom::InlineImage }, - { "JavaScript", Atom::JavaScript }, - { "EndJavaScript", Atom::EndJavaScript }, - { "Keyword", Atom::Keyword }, - { "LegaleseLeft", Atom::LegaleseLeft }, - { "LegaleseRight", Atom::LegaleseRight }, - { "LineBreak", Atom::LineBreak }, - { "Link", Atom::Link }, - { "LinkNode", Atom::LinkNode }, - { "ListLeft", Atom::ListLeft }, - { "ListItemNumber", Atom::ListItemNumber }, - { "ListTagLeft", Atom::ListTagLeft }, - { "ListTagRight", Atom::ListTagRight }, - { "ListItemLeft", Atom::ListItemLeft }, - { "ListItemRight", Atom::ListItemRight }, - { "ListRight", Atom::ListRight }, - { "NavAutoLink", Atom::NavAutoLink }, - { "NavLink", Atom::NavLink }, - { "Nop", Atom::Nop }, - { "NoteLeft", Atom::NoteLeft }, - { "NoteRight", Atom::NoteRight }, - { "ParaLeft", Atom::ParaLeft }, - { "ParaRight", Atom::ParaRight }, - { "Qml", Atom::Qml}, - { "QmlText", Atom::QmlText }, - { "QuotationLeft", Atom::QuotationLeft }, - { "QuotationRight", Atom::QuotationRight }, - { "RawString", Atom::RawString }, - { "SectionLeft", Atom::SectionLeft }, - { "SectionRight", Atom::SectionRight }, - { "SectionHeadingLeft", Atom::SectionHeadingLeft }, - { "SectionHeadingRight", Atom::SectionHeadingRight }, - { "SidebarLeft", Atom::SidebarLeft }, - { "SidebarRight", Atom::SidebarRight }, - { "SinceList", Atom::SinceList }, - { "SnippetCommand", Atom::SnippetCommand }, - { "SnippetIdentifier", Atom::SnippetIdentifier }, - { "SnippetLocation", Atom::SnippetLocation }, - { "String", Atom::String }, - { "TableLeft", Atom::TableLeft }, - { "TableRight", Atom::TableRight }, - { "TableHeaderLeft", Atom::TableHeaderLeft }, - { "TableHeaderRight", Atom::TableHeaderRight }, - { "TableRowLeft", Atom::TableRowLeft }, - { "TableRowRight", Atom::TableRowRight }, - { "TableItemLeft", Atom::TableItemLeft }, - { "TableItemRight", Atom::TableItemRight }, - { "TableOfContents", Atom::TableOfContents }, - { "Target", Atom::Target }, - { "UnhandledFormat", Atom::UnhandledFormat }, - { "UnknownCommand", Atom::UnknownCommand }, - { 0, 0 } -}; - -/*! \fn Atom::Atom(AtomType type, const QString& string) - - Constructs an atom of the specified \a type with the single - parameter \a string and does not put the new atom in a list. -*/ - -/*! \fn Atom::Atom(AtomType type, const QString& p1, const QString& p2) - - Constructs an atom of the specified \a type with the two - parameters \a p1 and \a p2 and does not put the new atom - in a list. -*/ - -/*! \fn Atom(Atom *previous, AtomType type, const QString& string) - - Constructs an atom of the specified \a type with the single - parameter \a string and inserts the new atom into the list - after the \a previous atom. -*/ - -/*! \fn Atom::Atom(Atom* previous, AtomType type, const QString& p1, const QString& p2) - - Constructs an atom of the specified \a type with the two - parameters \a p1 and \a p2 and inserts the new atom into - the list after the \a previous atom. -*/ - -/*! \fn void Atom::appendChar(QChar ch) - - Appends \a ch to the string parameter of this atom. - - \also string() -*/ - -/*! \fn void Atom::appendString(const QString& string) - - Appends \a string to the string parameter of this atom. - - \also string() -*/ - -/*! \fn void Atom::chopString() - - \also string() -*/ - -/*! \fn Atom *Atom::next() - Return the next atom in the atom list. - \also type(), string() -*/ - -/*! - Return the next Atom in the list if it is of AtomType \a t. - Otherwise return 0. - */ -const Atom* Atom::next(AtomType t) const -{ - return (next_ && (next_->type() == t)) ? next_ : 0; -} - -/*! - Return the next Atom in the list if it is of AtomType \a t - and its string part is \a s. Otherwise return 0. - */ -const Atom* Atom::next(AtomType t, const QString& s) const -{ - return (next_ && (next_->type() == t) && (next_->string() == s)) ? next_ : 0; -} - -/*! \fn const Atom *Atom::next() const - Return the next atom in the atom list. - \also type(), string() -*/ - -/*! \fn AtomType Atom::type() const - Return the type of this atom. - \also string(), next() -*/ - -/*! - Return the type of this atom as a string. Return "Invalid" if - type() returns an impossible value. - - This is only useful for debugging. - - \also type() -*/ -QString Atom::typeString() const -{ - static bool deja = false; - - if (!deja) { - int i = 0; - while (atms[i].english != 0) { - if (atms[i].no != i) - Location::internalError(QCoreApplication::translate("QDoc::Atom", "atom %1 missing").arg(i)); - i++; - } - deja = true; - } - - int i = (int) type(); - if (i < 0 || i > (int) Last) - return QLatin1String("Invalid"); - return QLatin1String(atms[i].english); -} - -/*! \fn const QString& Atom::string() const - - Returns the string parameter that together with the type - characterizes this atom. - - \also type(), next() -*/ - -/*! - Dumps this Atom to stderr in printer friendly form. - */ -void Atom::dump() const -{ - QString str = string(); - str.replace(QLatin1String("\\"), QLatin1String("\\\\")); - str.replace(QLatin1String("\""), QLatin1String("\\\"")); - str.replace(QLatin1String("\n"), QLatin1String("\\n")); - str.replace(QRegExp(QLatin1String("[^\x20-\x7e]")), QLatin1String("?")); - if (!str.isEmpty()) - str = QLatin1String(" \"") + str + QLatin1Char('"'); - fprintf(stderr, - " %-15s%s\n", - typeString().toLatin1().data(), - str.toLatin1().data()); -} - -/*! - The only constructor for LinkAtom. It creates an Atom of - type Atom::Link. \a p1 being the link target. \a p2 is the - parameters in square brackets. Normally there is just one - word in the square brackets, but there can be up to three - words separated by spaces. The constructor splits \a p2 on - the space character. - */ -LinkAtom::LinkAtom(const QString& p1, const QString& p2) - : Atom(p1), - resolved_(false), - genus_(Node::DontCare), - goal_(Node::NoType), - domain_(0), - squareBracketParams_(p2) -{ - // nada. -} - -/*! - This function resolves the parameters that were enclosed in - square brackets. If the parameters have already been resolved, - it does nothing and returns immediately. - */ -void LinkAtom::resolveSquareBracketParams() -{ - if (resolved_) - return; - QStringList params = squareBracketParams_.toLower().split(QLatin1Char(' ')); - foreach (const QString& p, params) { - if (!domain_) { - domain_ = QDocDatabase::qdocDB()->findTree(p); - if (domain_) { - continue; - } - } - if (goal_ == Node::NoType) { - goal_ = Node::goal(p); - if (goal_ != Node::NoType) - continue; - } - if (p == "qml") { - genus_ = Node::QML; - continue; - } - if (p == "cpp") { - genus_ = Node::CPP; - continue; - } - if (p == "doc") { - genus_ = Node::DOC; - continue; - } - error_ = squareBracketParams_; - break; - } - resolved_ = true; -} - -/*! - Standard copy constructor of LinkAtom \a t. - */ -LinkAtom::LinkAtom(const LinkAtom& t) - : Atom(Link, t.string()), - resolved_(t.resolved_), - genus_(t.genus_), - goal_(t.goal_), - domain_(t.domain_), - error_(t.error_), - squareBracketParams_(t.squareBracketParams_) -{ - // nothing -} - -/*! - Special copy constructor of LinkAtom \a t, where - where the new LinkAtom will not be the first one - in the list. - */ -LinkAtom::LinkAtom(Atom* previous, const LinkAtom& t) - : Atom(previous, Link, t.string()), - resolved_(t.resolved_), - genus_(t.genus_), - goal_(t.goal_), - domain_(t.domain_), - error_(t.error_), - squareBracketParams_(t.squareBracketParams_) -{ - previous->next_ = this; -} - -QT_END_NAMESPACE diff --git a/src/tools/qdoc/atom.h b/src/tools/qdoc/atom.h deleted file mode 100644 index 86b8ba7b3c..0000000000 --- a/src/tools/qdoc/atom.h +++ /dev/null @@ -1,257 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#ifndef ATOM_H -#define ATOM_H - -#include <qstringlist.h> -#include "node.h" -#include <qdebug.h> - -QT_BEGIN_NAMESPACE - -class Tree; -class LinkAtom; - -class Atom -{ -public: - enum AtomType { - AnnotatedList, - AutoLink, - BaseName, - BR, - BriefLeft, - BriefRight, - C, - CaptionLeft, - CaptionRight, - Code, - CodeBad, - CodeNew, - CodeOld, - CodeQuoteArgument, - CodeQuoteCommand, - DivLeft, - DivRight, - EndQmlText, - FootnoteLeft, - FootnoteRight, - FormatElse, - FormatEndif, - FormatIf, - FormattingLeft, - FormattingRight, - GeneratedList, - GuidLink, - HR, - Image, - ImageText, - ImportantLeft, - ImportantRight, - InlineImage, - JavaScript, - EndJavaScript, - Keyword, - LegaleseLeft, - LegaleseRight, - LineBreak, - Link, - LinkNode, - ListLeft, - ListItemNumber, - ListTagLeft, - ListTagRight, - ListItemLeft, - ListItemRight, - ListRight, - NavAutoLink, - NavLink, - Nop, - NoteLeft, - NoteRight, - ParaLeft, - ParaRight, - Qml, - QmlText, - QuotationLeft, - QuotationRight, - RawString, - SectionLeft, - SectionRight, - SectionHeadingLeft, - SectionHeadingRight, - SidebarLeft, - SidebarRight, - SinceList, - SnippetCommand, - SnippetIdentifier, - SnippetLocation, - String, - TableLeft, - TableRight, - TableHeaderLeft, - TableHeaderRight, - TableRowLeft, - TableRowRight, - TableItemLeft, - TableItemRight, - TableOfContents, - Target, - UnhandledFormat, - UnknownCommand, - Last = UnknownCommand - }; - - friend class LinkAtom; - - Atom(const QString& string) - : next_(0), type_(Link) - { - strs << string; - } - - Atom(AtomType type, const QString& string = "") - : next_(0), type_(type) - { - strs << string; - } - - Atom(AtomType type, const QString& p1, const QString& p2) - : next_(0), type_(type) - { - strs << p1; - if (!p2.isEmpty()) - strs << p2; - } - - Atom(Atom* previous, AtomType type, const QString& string = "") - : next_(previous->next_), type_(type) - { - strs << string; - previous->next_ = this; - } - - Atom(Atom* previous, AtomType type, const QString& p1, const QString& p2) - : next_(previous->next_), type_(type) - { - strs << p1; - if (!p2.isEmpty()) - strs << p2; - previous->next_ = this; - } - - virtual ~Atom() { } - - void appendChar(QChar ch) { strs[0] += ch; } - void appendString(const QString& string) { strs[0] += string; } - void chopString() { strs[0].chop(1); } - void setString(const QString& string) { strs[0] = string; } - Atom* next() { return next_; } - void setNext(Atom* newNext) { next_ = newNext; } - - const Atom* next() const { return next_; } - const Atom* next(AtomType t) const; - const Atom* next(AtomType t, const QString& s) const; - AtomType type() const { return type_; } - QString typeString() const; - const QString& string() const { return strs[0]; } - const QString& string(int i) const { return strs[i]; } - int count() const { return strs.size(); } - void dump() const; - const QStringList& strings() const { return strs; } - - virtual bool isLinkAtom() const { return false; } - virtual Node::Genus genus() { return Node::DontCare; } - virtual bool specifiesDomain() { return false; } - virtual Tree* domain() { return 0; } - virtual Node::NodeType goal() { return Node::NoType; } - virtual const QString& error() { return noError_; } - virtual void resolveSquareBracketParams() { } - - protected: - static QString noError_; - Atom* next_; - AtomType type_; - QStringList strs; -}; - -class LinkAtom : public Atom -{ - public: - LinkAtom(const QString& p1, const QString& p2); - LinkAtom(const LinkAtom& t); - LinkAtom(Atom* previous, const LinkAtom& t); - virtual ~LinkAtom() { } - - virtual bool isLinkAtom() const Q_DECL_OVERRIDE { return true; } - virtual Node::Genus genus() Q_DECL_OVERRIDE { resolveSquareBracketParams(); return genus_; } - virtual bool specifiesDomain() Q_DECL_OVERRIDE { resolveSquareBracketParams(); return (domain_ != 0); } - virtual Tree* domain() Q_DECL_OVERRIDE { resolveSquareBracketParams(); return domain_; } - virtual Node::NodeType goal() Q_DECL_OVERRIDE { resolveSquareBracketParams(); return goal_; } - virtual const QString& error() Q_DECL_OVERRIDE { return error_; } - virtual void resolveSquareBracketParams() Q_DECL_OVERRIDE; - - protected: - bool resolved_; - Node::Genus genus_; - Node::NodeType goal_; - Tree* domain_; - QString error_; - QString squareBracketParams_; -}; - -#define ATOM_FORMATTING_BOLD "bold" -#define ATOM_FORMATTING_INDEX "index" -#define ATOM_FORMATTING_ITALIC "italic" -#define ATOM_FORMATTING_LINK "link" -#define ATOM_FORMATTING_PARAMETER "parameter" -#define ATOM_FORMATTING_SPAN "span " -#define ATOM_FORMATTING_SUBSCRIPT "subscript" -#define ATOM_FORMATTING_SUPERSCRIPT "superscript" -#define ATOM_FORMATTING_TELETYPE "teletype" -#define ATOM_FORMATTING_UICONTROL "uicontrol" -#define ATOM_FORMATTING_UNDERLINE "underline" - -#define ATOM_LIST_BULLET "bullet" -#define ATOM_LIST_TAG "tag" -#define ATOM_LIST_VALUE "value" -#define ATOM_LIST_LOWERALPHA "loweralpha" -#define ATOM_LIST_LOWERROMAN "lowerroman" -#define ATOM_LIST_NUMERIC "numeric" -#define ATOM_LIST_UPPERALPHA "upperalpha" -#define ATOM_LIST_UPPERROMAN "upperroman" - -QT_END_NAMESPACE - -#endif diff --git a/src/tools/qdoc/codechunk.cpp b/src/tools/qdoc/codechunk.cpp deleted file mode 100644 index 5799e0bac0..0000000000 --- a/src/tools/qdoc/codechunk.cpp +++ /dev/null @@ -1,142 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/* - codechunk.cpp -*/ - -#include <qregexp.h> -#include <qstringlist.h> - -#include "codechunk.h" - -QT_BEGIN_NAMESPACE - -enum { Other, Alnum, Gizmo, Comma, LParen, RParen, RAngle, Colon }; - -// entries 128 and above are Other -static const int charCategory[256] = { - Other, Other, Other, Other, Other, Other, Other, Other, - Other, Other, Other, Other, Other, Other, Other, Other, - Other, Other, Other, Other, Other, Other, Other, Other, - Other, Other, Other, Other, Other, Other, Other, Other, - // ! " # $ % & ' - Other, Other, Other, Other, Other, Gizmo, Gizmo, Other, - // ( ) * + , - . / - LParen, RParen, Gizmo, Gizmo, Comma, Other, Other, Gizmo, - // 0 1 2 3 4 5 6 7 - Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, - // 8 9 : ; < = > ? - Alnum, Alnum, Colon, Other, Other, Gizmo, RAngle, Gizmo, - // @ A B C D E F G - Other, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, - // H I J K L M N O - Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, - // P Q R S T U V W - Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, - // X Y Z [ \ ] ^ _ - Alnum, Alnum, Alnum, Other, Other, Other, Gizmo, Alnum, - // ` a b c d e f g - Other, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, - // h i j k l m n o - Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, - // p q r s t u v w - Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, Alnum, - // x y z { | } ~ - Alnum, Alnum, Alnum, LParen, Gizmo, RParen, Other, Other -}; - -static const bool needSpace[8][8] = { - /* [ a + , ( ) > : */ - /* [ */ { false, false, false, false, false, true, false, false }, - /* a */ { false, true, true, false, false, true, false, false }, - /* + */ { false, true, false, false, false, true, false, true }, - /* , */ { true, true, true, true, true, true, true, true }, - /* ( */ { true, true, true, false, true, false, true, true }, - /* ) */ { true, true, true, false, true, true, true, true }, - /* > */ { true, true, true, false, true, true, true, false }, - /* : */ { false, false, true, true, true, true, true, false } -}; - -static int category( QChar ch ) -{ - return charCategory[(int)ch.toLatin1()]; -} - -CodeChunk::CodeChunk() - : hotspot( -1 ) -{ -} - -CodeChunk::CodeChunk( const QString& str ) - : s( str ), hotspot( -1 ) -{ -} - -void CodeChunk::append( const QString& lexeme ) -{ - if ( !s.isEmpty() && !lexeme.isEmpty() ) { - /* - Should there be a space or not between the code chunk so far and the - new lexeme? - */ - int cat1 = category(s.at(s.size() - 1)); - int cat2 = category(lexeme[0]); - if ( needSpace[cat1][cat2] ) - s += QLatin1Char( ' ' ); - } - s += lexeme; -} - -void CodeChunk::appendHotspot() -{ - /* - The first hotspot is the right one. - */ - if ( hotspot == -1 ) - hotspot = s.length(); -} - -QString CodeChunk::toString() const -{ - return s; -} - -QStringList CodeChunk::toPath() const -{ - QString t = s; - t.remove(QRegExp(QLatin1String("<([^<>]|<([^<>]|<[^<>]*>)*>)*>"))); - return t.split(QLatin1String("::")); -} - -QT_END_NAMESPACE diff --git a/src/tools/qdoc/codechunk.h b/src/tools/qdoc/codechunk.h deleted file mode 100644 index 259012df90..0000000000 --- a/src/tools/qdoc/codechunk.h +++ /dev/null @@ -1,116 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/* - codechunk.h -*/ - -#ifndef CODECHUNK_H -#define CODECHUNK_H - -#include <qstring.h> - -QT_BEGIN_NAMESPACE - -// ### get rid of that class - -/* - The CodeChunk class represents a tiny piece of C++ code. - - The class provides conversion between a list of lexemes and a string. It adds - spaces at the right place for consistent style. The tiny pieces of code it - represents are data types, enum values, and default parameter values. - - Apart from the piece of code itself, there are two bits of metainformation - stored in CodeChunk: the base and the hotspot. The base is the part of the - piece that may be a hypertext link. The base of - - QMap<QString, QString> - - is QMap. - - The hotspot is the place the variable name should be inserted in the case of a - variable (or parameter) declaration. The base of - - char * [] - - is between '*' and '[]'. -*/ -class CodeChunk -{ -public: - CodeChunk(); - CodeChunk( const QString& str ); - - void append( const QString& lexeme ); - void appendHotspot(); - - bool isEmpty() const { return s.isEmpty(); } - void clear() { s.clear(); } - QString toString() const; - QStringList toPath() const; - QString left() const { return s.left(hotspot == -1 ? s.length() : hotspot); } - QString right() const { return s.mid(hotspot == -1 ? s.length() : hotspot); } - -private: - QString s; - int hotspot; -}; - -inline bool operator==( const CodeChunk& c, const CodeChunk& d ) { - return c.toString() == d.toString(); -} - -inline bool operator!=( const CodeChunk& c, const CodeChunk& d ) { - return !( c == d ); -} - -inline bool operator<( const CodeChunk& c, const CodeChunk& d ) { - return c.toString() < d.toString(); -} - -inline bool operator>( const CodeChunk& c, const CodeChunk& d ) { - return d < c; -} - -inline bool operator<=( const CodeChunk& c, const CodeChunk& d ) { - return !( c > d ); -} - -inline bool operator>=( const CodeChunk& c, const CodeChunk& d ) { - return !( c < d ); -} - -QT_END_NAMESPACE - -#endif diff --git a/src/tools/qdoc/codemarker.cpp b/src/tools/qdoc/codemarker.cpp deleted file mode 100644 index a668205a66..0000000000 --- a/src/tools/qdoc/codemarker.cpp +++ /dev/null @@ -1,668 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include <qobjectdefs.h> -#include "codemarker.h" -#include "config.h" -#include "node.h" -#include <qdebug.h> -#include <stdio.h> - -QT_BEGIN_NAMESPACE - -QString CodeMarker::defaultLang; -QList<CodeMarker *> CodeMarker::markers; - -/*! - When a code marker constructs itself, it puts itself into - the static list of code markers. All the code markers in - the static list get initialized in initialize(), which is - not called until after the qdoc configuration file has - been read. - */ -CodeMarker::CodeMarker() -{ - markers.prepend(this); -} - -/*! - When a code marker destroys itself, it removes itself from - the static list of code markers. - */ -CodeMarker::~CodeMarker() -{ - markers.removeAll(this); -} - -/*! - A code market performs no initialization by default. Marker-specific - initialization is performed in subclasses. - */ -void CodeMarker::initializeMarker(const Config& ) // config -{ -} - -/*! - Terminating a code marker is trivial. - */ -void CodeMarker::terminateMarker() -{ - // nothing. -} - -/*! - All the code markers in the static list are initialized - here, after the qdoc configuration file has been loaded. - */ -void CodeMarker::initialize(const Config& config) -{ - defaultLang = config.getString(CONFIG_LANGUAGE); - QList<CodeMarker *>::ConstIterator m = markers.constBegin(); - while (m != markers.constEnd()) { - (*m)->initializeMarker(config); - ++m; - } -} - -/*! - All the code markers in the static list are terminated here. - */ -void CodeMarker::terminate() -{ - QList<CodeMarker *>::ConstIterator m = markers.constBegin(); - while (m != markers.constEnd()) { - (*m)->terminateMarker(); - ++m; - } -} - -CodeMarker *CodeMarker::markerForCode(const QString& code) -{ - CodeMarker *defaultMarker = markerForLanguage(defaultLang); - if (defaultMarker != 0 && defaultMarker->recognizeCode(code)) - return defaultMarker; - - QList<CodeMarker *>::ConstIterator m = markers.constBegin(); - while (m != markers.constEnd()) { - if ((*m)->recognizeCode(code)) - return *m; - ++m; - } - return defaultMarker; -} - -CodeMarker *CodeMarker::markerForFileName(const QString& fileName) -{ - CodeMarker *defaultMarker = markerForLanguage(defaultLang); - int dot = -1; - while ((dot = fileName.lastIndexOf(QLatin1Char('.'), dot)) != -1) { - QString ext = fileName.mid(dot + 1); - if (defaultMarker != 0 && defaultMarker->recognizeExtension(ext)) - return defaultMarker; - QList<CodeMarker *>::ConstIterator m = markers.constBegin(); - while (m != markers.constEnd()) { - if ((*m)->recognizeExtension(ext)) - return *m; - ++m; - } - --dot; - } - return defaultMarker; -} - -CodeMarker *CodeMarker::markerForLanguage(const QString& lang) -{ - QList<CodeMarker *>::ConstIterator m = markers.constBegin(); - while (m != markers.constEnd()) { - if ((*m)->recognizeLanguage(lang)) - return *m; - ++m; - } - return 0; -} - -const Node *CodeMarker::nodeForString(const QString& string) -{ - if (sizeof(const Node *) == sizeof(uint)) { - return reinterpret_cast<const Node *>(string.toUInt()); - } - else { - return reinterpret_cast<const Node *>(string.toULongLong()); - } -} - -QString CodeMarker::stringForNode(const Node *node) -{ - if (sizeof(const Node *) == sizeof(ulong)) { - return QString::number(reinterpret_cast<quintptr>(node)); - } - else { - return QString::number(reinterpret_cast<qulonglong>(node)); - } -} - -static const QString samp = QLatin1String("&"); -static const QString slt = QLatin1String("<"); -static const QString sgt = QLatin1String(">"); -static const QString squot = QLatin1String("""); - -QString CodeMarker::protect(const QString& str) -{ - int n = str.length(); - QString marked; - marked.reserve(n * 2 + 30); - const QChar *data = str.constData(); - for (int i = 0; i != n; ++i) { - switch (data[i].unicode()) { - case '&': marked += samp; break; - case '<': marked += slt; break; - case '>': marked += sgt; break; - case '"': marked += squot; break; - default : marked += data[i]; - } - } - return marked; -} - -void CodeMarker::appendProtectedString(QString *output, const QStringRef &str) -{ - int n = str.length(); - output->reserve(output->size() + n * 2 + 30); - const QChar *data = str.constData(); - for (int i = 0; i != n; ++i) { - switch (data[i].unicode()) { - case '&': *output += samp; break; - case '<': *output += slt; break; - case '>': *output += sgt; break; - case '"': *output += squot; break; - default : *output += data[i]; - } - } -} - -QString CodeMarker::typified(const QString &string, bool trailingSpace) -{ - QString result; - QString pendingWord; - - for (int i = 0; i <= string.size(); ++i) { - QChar ch; - if (i != string.size()) - ch = string.at(i); - - QChar lower = ch.toLower(); - if ((lower >= QLatin1Char('a') && lower <= QLatin1Char('z')) - || ch.digitValue() >= 0 || ch == QLatin1Char('_') - || ch == QLatin1Char(':')) { - pendingWord += ch; - } - else { - if (!pendingWord.isEmpty()) { - bool isProbablyType = (pendingWord != QLatin1String("const")); - if (isProbablyType) - result += QLatin1String("<@type>"); - result += pendingWord; - if (isProbablyType) - result += QLatin1String("</@type>"); - } - pendingWord.clear(); - - switch (ch.unicode()) { - case '\0': - break; - case '&': - result += QLatin1String("&"); - break; - case '<': - result += QLatin1String("<"); - break; - case '>': - result += QLatin1String(">"); - break; - default: - result += ch; - } - } - } - if (trailingSpace && string.size()) { - if (!string.endsWith(QLatin1Char('*')) - && !string.endsWith(QLatin1Char('&'))) - result += QLatin1Char(' '); - } - return result; -} - -QString CodeMarker::taggedNode(const Node* node) -{ - QString tag; - QString name = node->name(); - - switch (node->type()) { - case Node::Namespace: - tag = QLatin1String("@namespace"); - break; - case Node::Class: - tag = QLatin1String("@class"); - break; - case Node::Enum: - tag = QLatin1String("@enum"); - break; - case Node::Typedef: - tag = QLatin1String("@typedef"); - break; - case Node::Function: - tag = QLatin1String("@function"); - break; - case Node::Property: - tag = QLatin1String("@property"); - break; - case Node::QmlType: - /* - Remove the "QML:" prefix, if present. - There shouldn't be any of these "QML:" - prefixes in the documentation sources - after the switch to using QML module - qualifiers, but this code is kept to - be backward compatible. - */ - if (node->name().startsWith(QLatin1String("QML:"))) - name = name.mid(4); - tag = QLatin1String("@property"); - break; - case Node::Document: - tag = QLatin1String("@property"); - break; - case Node::QmlMethod: - case Node::QmlSignal: - case Node::QmlSignalHandler: - tag = QLatin1String("@function"); - break; - default: - tag = QLatin1String("@unknown"); - break; - } - return (QLatin1Char('<') + tag + QLatin1Char('>') + protect(name) - + QLatin1String("</") + tag + QLatin1Char('>')); -} - -QString CodeMarker::taggedQmlNode(const Node* node) -{ - QString tag; - switch (node->type()) { - case Node::QmlProperty: - tag = QLatin1String("@property"); - break; - case Node::QmlSignal: - tag = QLatin1String("@signal"); - break; - case Node::QmlSignalHandler: - tag = QLatin1String("@signalhandler"); - break; - case Node::QmlMethod: - tag = QLatin1String("@method"); - break; - default: - tag = QLatin1String("@unknown"); - break; - } - return QLatin1Char('<') + tag + QLatin1Char('>') + protect(node->name()) - + QLatin1String("</") + tag + QLatin1Char('>'); -} - -QString CodeMarker::linkTag(const Node *node, const QString& body) -{ - return QLatin1String("<@link node=\"") + stringForNode(node) - + QLatin1String("\">") + body + QLatin1String("</@link>"); -} - -QString CodeMarker::sortName(const Node *node, const QString* name) -{ - QString nodeName; - if (name != 0) - nodeName = *name; - else - nodeName = node->name(); - int numDigits = 0; - for (int i = nodeName.size() - 1; i > 0; --i) { - if (nodeName.at(i).digitValue() == -1) - break; - ++numDigits; - } - - // we want 'qint8' to appear before 'qint16' - if (numDigits > 0) { - for (int i = 0; i < 4 - numDigits; ++i) - nodeName.insert(nodeName.size()-numDigits-1, QLatin1Char('0')); - } - - if (node->type() == Node::Function) { - const FunctionNode *func = static_cast<const FunctionNode *>(node); - QString sortNo; - if (func->metaness() == FunctionNode::Ctor) { - sortNo = QLatin1String("C"); - } - else if (func->metaness() == FunctionNode::Dtor) { - sortNo = QLatin1String("D"); - } - else { - if (nodeName.startsWith(QLatin1String("operator")) - && nodeName.length() > 8 - && !nodeName[8].isLetterOrNumber()) - sortNo = QLatin1String("F"); - else - sortNo = QLatin1String("E"); - } - return sortNo + nodeName + QLatin1Char(' ') + QString::number(func->overloadNumber(), 36); - } - - if (node->type() == Node::Class) - return QLatin1Char('A') + nodeName; - - if (node->type() == Node::Property || node->type() == Node::Variable) - return QLatin1Char('E') + nodeName; - - if ((node->type() == Node::QmlMethod) || - (node->type() == Node::QmlSignal) || - (node->type() == Node::QmlSignalHandler)) { - //const FunctionNode* func = static_cast<const FunctionNode *>(node); - //return QLatin1Char('E') + func->name(); - return QLatin1Char('E') + nodeName; - } - - return QLatin1Char('B') + nodeName; -} - -void CodeMarker::insert(FastSection &fastSection, - Node *node, - SynopsisStyle style, - Status status) -{ - bool irrelevant = false; - bool inheritedMember = false; - if (!node->relates()) { - Aggregate* p = node->parent(); - if (p->isQmlPropertyGroup()) - p = p->parent(); - if (p != fastSection.parent_) { - if ((!p->isQmlType() && !p->isJsType()) || !p->isAbstract()) - inheritedMember = true; - } - } - - if (node->access() == Node::Private) { - irrelevant = true; - } - else if (node->type() == Node::Function) { - FunctionNode *func = (FunctionNode *) node; - irrelevant = (inheritedMember - && (func->metaness() == FunctionNode::Ctor || - func->metaness() == FunctionNode::Dtor)); - } - else if (node->type() == Node::Class || node->type() == Node::Enum - || node->type() == Node::Typedef) { - irrelevant = (inheritedMember && style != Subpage); - if (!irrelevant && style == Detailed && node->type() == Node::Typedef) { - const TypedefNode* typedeffe = static_cast<const TypedefNode*>(node); - if (typedeffe->associatedEnum()) - irrelevant = true; - } - } - - if (!irrelevant) { - if (status == Compat) { - irrelevant = (node->status() != Node::Compat); - } - else if (status == Obsolete) { - irrelevant = (node->status() != Node::Obsolete); - } - else { - irrelevant = (node->status() == Node::Compat || - node->status() == Node::Obsolete); - } - } - - if (!irrelevant) { - if (!inheritedMember || style == Subpage) { - QString key = sortName(node); - fastSection.memberMap.insertMulti(key, node); - } - else { - if (node->parent()->isClass() || node->parent()->isNamespace()) { - if (fastSection.inherited.isEmpty() - || fastSection.inherited.last().first != node->parent()) { - QPair<Aggregate *, int> p(node->parent(), 0); - fastSection.inherited.append(p); - } - fastSection.inherited.last().second++; - } - } - } -} - -/*! - Returns \c true if \a node represents a reimplemented member - function in the class of the FastSection \a fs. If it is - a reimplemented function, then it is inserted into the - reimplemented member map in \a fs. The test is performed - only if \a status is \e OK. True is returned if \a node - is inserted into the map. Otherwise, false is returned. - */ -bool CodeMarker::insertReimpFunc(FastSection& fs, Node* node, Status status) -{ - if ((node->access() != Node::Private) && (node->relates() == 0)) { - const FunctionNode* fn = static_cast<const FunctionNode*>(node); - if ((fn->reimplementedFrom() != 0) && (status == Okay)) { - if (fn->parent() == fs.parent_) { - QString key = sortName(fn); - if (!fs.reimpMemberMap.contains(key)) { - fs.reimpMemberMap.insert(key,node); - return true; - } - } - } - } - return false; -} - -/*! - If \a fs is not empty, convert it to a Section and append - the new Section to \a sectionList. - */ -void CodeMarker::append(QList<Section>& sectionList, const FastSection& fs, bool includeKeys) -{ - if (!fs.isEmpty()) { - if (fs.classMapList_.isEmpty()) { - Section section(fs.name,fs.divClass,fs.singularMember,fs.pluralMember); - if (includeKeys) { - section.keys = fs.memberMap.keys(); - } - section.members = fs.memberMap.values(); - section.reimpMembers = fs.reimpMemberMap.values(); - section.inherited = fs.inherited; - sectionList.append(section); - } - else { - Section section(fs.name,fs.divClass,fs.singularMember,fs.pluralMember); - sectionList.append(section); - Section* s = §ionList[sectionList.size()-1]; - for (int i=0; i<fs.classMapList_.size(); i++) { - ClassMap* classMap = fs.classMapList_[i]; - ClassKeysNodes* ckn = new ClassKeysNodes; - ckn->first = classMap->first; - ckn->second.second = classMap->second.values(); - ckn->second.first = classMap->second.keys(); - s->classKeysNodesList_.append(ckn); - } - } - } -} - -/*! - The destructor must delete each member of the - list of QML class lists, if it is not empty; - */ -Section::~Section() -{ - if (!classKeysNodesList_.isEmpty()) { - for (int i=0; i<classKeysNodesList_.size(); i++) { - ClassKeysNodes* classKeysNodes = classKeysNodesList_[i]; - classKeysNodesList_[i] = 0; - delete classKeysNodes; - } - } -} - -/*! - The destructor must delete the QML class maps in the class - map list, if the class map list is not empty. - */ -FastSection::~FastSection() -{ - if (!classMapList_.isEmpty()) { - for (int i=0; i<classMapList_.size(); i++) { - ClassMap* classMap = classMapList_[i]; - classMapList_[i] = 0; - delete classMap; - } - } -} - -static QString encode(const QString &string) -{ - return string; -} - -QStringList CodeMarker::macRefsForNode(Node *node) -{ - QString result = QLatin1String("cpp/"); - switch (node->type()) { - case Node::Class: - { - const ClassNode *classe = static_cast<const ClassNode *>(node); - { - result += QLatin1String("cl/"); - } - result += macName(classe); // ### Maybe plainName? - } - break; - case Node::Enum: - { - QStringList stringList; - stringList << encode(result + QLatin1String("tag/") + - macName(node)); - foreach (const QString &enumName, node->doc().enumItemNames()) { - // ### Write a plainEnumValue() and use it here - stringList << encode(result + QLatin1String("econst/") + - macName(node->parent(), enumName)); - } - return stringList; - } - case Node::Typedef: - result += QLatin1String("tdef/") + macName(node); - break; - case Node::Function: - { - bool isMacro = false; - Q_UNUSED(isMacro) - const FunctionNode *func = static_cast<const FunctionNode *>(node); - - // overloads are too clever for the Xcode documentation browser - if (func->isOverload()) - return QStringList(); - - if (func->metaness() == FunctionNode::MacroWithParams - || func->metaness() == FunctionNode::MacroWithoutParams) { - result += QLatin1String("macro/"); - } - else if (func->isStatic()) { - result += QLatin1String("clm/"); - } - else if (!func->parent()->name().isEmpty()) { - result += QLatin1String("instm/"); - } - else { - result += QLatin1String("func/"); - } - - result += macName(func); - if (result.endsWith(QLatin1String("()"))) - result.chop(2); - } - break; - case Node::Variable: - result += QLatin1String("data/") + macName(node); - break; - case Node::Property: - { - NodeList list = static_cast<const PropertyNode*>(node)->functions(); - QStringList stringList; - foreach (Node* node, list) { - stringList += macRefsForNode(node); - } - return stringList; - } - case Node::Namespace: - case Node::Document: - case Node::QmlType: - default: - return QStringList(); - } - - return QStringList(encode(result)); -} - -QString CodeMarker::macName(const Node *node, const QString &name) -{ - QString myName = name; - if (myName.isEmpty()) { - myName = node->name(); - node = node->parent(); - } - - if (node->name().isEmpty()) { - return QLatin1Char('/') + protect(myName); - } - else { - return node->plainFullName() + QLatin1Char('/') + protect(myName); - } -} - -/*! - Returns an empty list of documentation sections. - */ -QList<Section> CodeMarker::qmlSections(QmlTypeNode* , SynopsisStyle , Status ) -{ - return QList<Section>(); -} - -QT_END_NAMESPACE diff --git a/src/tools/qdoc/codemarker.h b/src/tools/qdoc/codemarker.h deleted file mode 100644 index 011c8623dd..0000000000 --- a/src/tools/qdoc/codemarker.h +++ /dev/null @@ -1,187 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/* - codemarker.h -*/ - -#ifndef CODEMARKER_H -#define CODEMARKER_H - -#include <qpair.h> - -#include "atom.h" -#include "node.h" - -QT_BEGIN_NAMESPACE - -class Config; - -typedef QMultiMap<QString, Node*> MemberMap; // the string is the member signature -typedef QPair<const QmlTypeNode*, MemberMap> ClassMap; // the node is the QML type -typedef QList<ClassMap*> ClassMapList; - -typedef QPair<QStringList, NodeList> KeysAndNodes; -typedef QPair<const QmlTypeNode*, KeysAndNodes> ClassKeysNodes; -typedef QList<ClassKeysNodes*> ClassKeysNodesList; - -struct Section -{ - QString name; - QString divClass; - QString singularMember; - QString pluralMember; - QStringList keys; - NodeList members; - NodeList reimpMembers; - QList<QPair<Aggregate *, int> > inherited; - ClassKeysNodesList classKeysNodesList_; - - Section() { } - Section(const QString& name0, - const QString& divClass0, - const QString& singularMember0, - const QString& pluralMember0) - : name(name0), - divClass(divClass0), - singularMember(singularMember0), - pluralMember(pluralMember0) { } - ~Section(); - void appendMember(Node* node) { members.append(node); } - void appendReimpMember(Node* node) { reimpMembers.append(node); } -}; - -struct FastSection -{ - const Aggregate *parent_; - QString name; - QString divClass; - QString singularMember; - QString pluralMember; - QMultiMap<QString, Node *> memberMap; - QMultiMap<QString, Node *> reimpMemberMap; - ClassMapList classMapList_; - QList<QPair<Aggregate *, int> > inherited; - - FastSection(const Aggregate *parent, - const QString& name0, - const QString& divClass0, - const QString& singularMember0, - const QString& pluralMember0) - : parent_(parent), - name(name0), - divClass(divClass0), - singularMember(singularMember0), - pluralMember(pluralMember0) { } - ~FastSection(); - bool isEmpty() const { - return (memberMap.isEmpty() && - inherited.isEmpty() && - reimpMemberMap.isEmpty() && - classMapList_.isEmpty()); - } - -}; - -class CodeMarker -{ -public: - enum SynopsisStyle { Summary, Detailed, Subpage, Accessors }; - enum Status { Compat, Obsolete, Okay }; - - CodeMarker(); - virtual ~CodeMarker(); - - virtual void initializeMarker(const Config& config); - virtual void terminateMarker(); - virtual bool recognizeCode(const QString& code) = 0; - virtual bool recognizeExtension(const QString& ext) = 0; - virtual bool recognizeLanguage(const QString& lang) = 0; - virtual Atom::AtomType atomType() const = 0; - virtual QString markedUpCode(const QString& code, - const Node *relative, - const Location &location) = 0; - virtual QString markedUpSynopsis(const Node *node, - const Node *relative, - SynopsisStyle style) = 0; - virtual QString markedUpQmlItem(const Node* , bool) { return QString(); } - virtual QString markedUpName(const Node *node) = 0; - virtual QString markedUpFullName(const Node *node, - const Node *relative = 0) = 0; - virtual QString markedUpEnumValue(const QString &enumValue, - const Node *relative) = 0; - virtual QString markedUpIncludes(const QStringList& includes) = 0; - virtual QString functionBeginRegExp(const QString& funcName) = 0; - virtual QString functionEndRegExp(const QString& funcName) = 0; - virtual QList<Section> sections(const Aggregate *inner, - SynopsisStyle style, - Status status) = 0; - virtual QList<Section> qmlSections(QmlTypeNode* qmlTypeNode, - SynopsisStyle style, - Status status = Okay); - virtual QStringList macRefsForNode(Node* node); - - static void initialize(const Config& config); - static void terminate(); - static CodeMarker *markerForCode(const QString& code); - static CodeMarker *markerForFileName(const QString& fileName); - static CodeMarker *markerForLanguage(const QString& lang); - static const Node *nodeForString(const QString& string); - static QString stringForNode(const Node *node); - - QString typified(const QString &string, bool trailingSpace = false); - -protected: - virtual QString sortName(const Node *node, const QString* name = 0); - static QString protect(const QString &string); - static void appendProtectedString(QString *output, const QStringRef &str); - QString taggedNode(const Node* node); - QString taggedQmlNode(const Node* node); - QString linkTag(const Node *node, const QString& body); - void insert(FastSection &fastSection, - Node *node, - SynopsisStyle style, - Status status); - bool insertReimpFunc(FastSection& fs, Node* node, Status status); - void append(QList<Section>& sectionList, const FastSection& fastSection, bool includeKeys = false); - -private: - QString macName(const Node *parent, const QString &name = QString()); - - static QString defaultLang; - static QList<CodeMarker *> markers; -}; - -QT_END_NAMESPACE - -#endif diff --git a/src/tools/qdoc/codeparser.cpp b/src/tools/qdoc/codeparser.cpp deleted file mode 100644 index 92a0d52129..0000000000 --- a/src/tools/qdoc/codeparser.cpp +++ /dev/null @@ -1,437 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/* - codeparser.cpp -*/ - -#include "codeparser.h" -#include "node.h" -#include "tree.h" -#include "config.h" -#include "generator.h" -#include "qdocdatabase.h" -#include <qdebug.h> - -QT_BEGIN_NAMESPACE - -#define COMMAND_COMPAT Doc::alias(QLatin1String("compat")) -#define COMMAND_DEPRECATED Doc::alias(QLatin1String("deprecated")) // ### don't document -#define COMMAND_INGROUP Doc::alias(QLatin1String("ingroup")) -#define COMMAND_INMODULE Doc::alias(QLatin1String("inmodule")) // ### don't document -#define COMMAND_INQMLMODULE Doc::alias(QLatin1String("inqmlmodule")) -#define COMMAND_INJSMODULE Doc::alias(QLatin1String("injsmodule")) -#define COMMAND_INTERNAL Doc::alias(QLatin1String("internal")) -#define COMMAND_MAINCLASS Doc::alias(QLatin1String("mainclass")) -#define COMMAND_NONREENTRANT Doc::alias(QLatin1String("nonreentrant")) -#define COMMAND_OBSOLETE Doc::alias(QLatin1String("obsolete")) -#define COMMAND_PAGEKEYWORDS Doc::alias(QLatin1String("pagekeywords")) -#define COMMAND_PRELIMINARY Doc::alias(QLatin1String("preliminary")) -#define COMMAND_INPUBLICGROUP Doc::alias(QLatin1String("inpublicgroup")) -#define COMMAND_QTVARIABLE Doc::alias(QLatin1String("qtvariable")) -#define COMMAND_REENTRANT Doc::alias(QLatin1String("reentrant")) -#define COMMAND_SINCE Doc::alias(QLatin1String("since")) -#define COMMAND_SUBTITLE Doc::alias(QLatin1String("subtitle")) -#define COMMAND_THREADSAFE Doc::alias(QLatin1String("threadsafe")) -#define COMMAND_TITLE Doc::alias(QLatin1String("title")) -#define COMMAND_WRAPPER Doc::alias(QLatin1String("wrapper")) -#define COMMAND_NOAUTOLIST Doc::alias(QLatin1String("noautolist")) - -QList<CodeParser *> CodeParser::parsers; -bool CodeParser::showInternal_ = false; -bool CodeParser::singleExec_ = false; - -/*! - The constructor adds this code parser to the static - list of code parsers. - */ -CodeParser::CodeParser() -{ - qdb_ = QDocDatabase::qdocDB(); - parsers.prepend(this); -} - -/*! - The destructor removes this code parser from the static - list of code parsers. - */ -CodeParser::~CodeParser() -{ - parsers.removeAll(this); -} - -/*! - Initialize the code parser base class. - */ -void CodeParser::initializeParser(const Config& config) -{ - showInternal_ = config.getBool(CONFIG_SHOWINTERNAL); - singleExec_ = config.getBool(CONFIG_SINGLEEXEC); -} - -/*! - Terminating a code parser is trivial. - */ -void CodeParser::terminateParser() -{ - // nothing. -} - -QStringList CodeParser::headerFileNameFilter() -{ - return sourceFileNameFilter(); -} - -void CodeParser::parseHeaderFile(const Location& location, const QString& filePath) -{ - parseSourceFile(location, filePath); -} - -void CodeParser::doneParsingHeaderFiles() -{ - doneParsingSourceFiles(); -} - -/*! - All the code parsers in the static list are initialized here, - after the qdoc configuration variables have been set. - */ -void CodeParser::initialize(const Config& config) -{ - QList<CodeParser *>::ConstIterator p = parsers.constBegin(); - while (p != parsers.constEnd()) { - (*p)->initializeParser(config); - ++p; - } -} - -/*! - All the code parsers in the static list are terminated here. - */ -void CodeParser::terminate() -{ - QList<CodeParser *>::ConstIterator p = parsers.constBegin(); - while (p != parsers.constEnd()) { - (*p)->terminateParser(); - ++p; - } -} - -CodeParser *CodeParser::parserForLanguage(const QString& language) -{ - QList<CodeParser *>::ConstIterator p = parsers.constBegin(); - while (p != parsers.constEnd()) { - if ((*p)->language() == language) - return *p; - ++p; - } - return 0; -} - -CodeParser *CodeParser::parserForHeaderFile(const QString &filePath) -{ - QString fileName = QFileInfo(filePath).fileName(); - - QList<CodeParser *>::ConstIterator p = parsers.constBegin(); - while (p != parsers.constEnd()) { - - QStringList headerPatterns = (*p)->headerFileNameFilter(); - foreach (const QString &pattern, headerPatterns) { - QRegExp re(pattern, Qt::CaseInsensitive, QRegExp::Wildcard); - if (re.exactMatch(fileName)) - return *p; - } - ++p; - } - return 0; -} - -CodeParser *CodeParser::parserForSourceFile(const QString &filePath) -{ - QString fileName = QFileInfo(filePath).fileName(); - - QList<CodeParser *>::ConstIterator p = parsers.constBegin(); - while (p != parsers.constEnd()) { - - QStringList sourcePatterns = (*p)->sourceFileNameFilter(); - foreach (const QString &pattern, sourcePatterns) { - QRegExp re(pattern, Qt::CaseInsensitive, QRegExp::Wildcard); - if (re.exactMatch(fileName)) - return *p; - } - ++p; - } - return 0; -} - -static QSet<QString> commonMetaCommands_; -/*! - Returns the set of strings representing the common metacommands. - */ -const QSet<QString>& CodeParser::commonMetaCommands() -{ - if (commonMetaCommands_.isEmpty()) { - commonMetaCommands_ << COMMAND_COMPAT - << COMMAND_DEPRECATED - << COMMAND_INGROUP - << COMMAND_INMODULE - << COMMAND_INQMLMODULE - << COMMAND_INTERNAL - << COMMAND_MAINCLASS - << COMMAND_NONREENTRANT - << COMMAND_OBSOLETE - << COMMAND_PAGEKEYWORDS - << COMMAND_PRELIMINARY - << COMMAND_INPUBLICGROUP - << COMMAND_QTVARIABLE - << COMMAND_REENTRANT - << COMMAND_SINCE - << COMMAND_SUBTITLE - << COMMAND_THREADSAFE - << COMMAND_TITLE - << COMMAND_WRAPPER - << COMMAND_INJSMODULE - << COMMAND_NOAUTOLIST; - } - return commonMetaCommands_; -} - -/*! - The topic command has been processed. Now process the other - metacommands that were found. These are not the text markup - commands. - */ -void CodeParser::processCommonMetaCommand(const Location& location, - const QString& command, - const ArgLocPair& arg, - Node* node) -{ - if (command == COMMAND_COMPAT) { - location.warning(tr("\\compat command used, but Qt3 compatibility is no longer supported")); - node->setStatus(Node::Compat); - } - else if (command == COMMAND_DEPRECATED) { - node->setStatus(Node::Obsolete); - } - else if ((command == COMMAND_INGROUP) || (command == COMMAND_INPUBLICGROUP)) { - // Note: \ingroup and \inpublicgroup are now the same. - // Not that they were ever different. - qdb_->addToGroup(arg.first, node); - } - else if (command == COMMAND_INMODULE) { - qdb_->addToModule(arg.first,node); - } - else if (command == COMMAND_INQMLMODULE) { - qdb_->addToQmlModule(arg.first,node); - } - else if (command == COMMAND_INJSMODULE) { - qdb_->addToJsModule(arg.first, node); - } - else if (command == COMMAND_MAINCLASS) { - node->doc().location().warning(tr("'\\mainclass' is deprecated. Consider '\\ingroup mainclasses'")); - } - else if (command == COMMAND_OBSOLETE) { - node->setStatus(Node::Obsolete); - } - else if (command == COMMAND_NONREENTRANT) { - node->setThreadSafeness(Node::NonReentrant); - } - else if (command == COMMAND_PRELIMINARY) { - node->setStatus(Node::Preliminary); - } - else if (command == COMMAND_INTERNAL) { - if (!showInternal_) { - node->setAccess(Node::Private); - node->setStatus(Node::Internal); - if (node->type() == Node::QmlPropertyGroup) { - const QmlPropertyGroupNode* qpgn = static_cast<const QmlPropertyGroupNode*>(node); - NodeList::ConstIterator p = qpgn->childNodes().constBegin(); - while (p != qpgn->childNodes().constEnd()) { - if ((*p)->type() == Node::QmlProperty) { - (*p)->setAccess(Node::Private); - (*p)->setStatus(Node::Internal); - } - ++p; - } - } - } - } - else if (command == COMMAND_REENTRANT) { - node->setThreadSafeness(Node::Reentrant); - } - else if (command == COMMAND_SINCE) { - node->setSince(arg.first); - } - else if (command == COMMAND_WRAPPER) { - node->setWrapper(); - } - else if (command == COMMAND_PAGEKEYWORDS) { - node->addPageKeywords(arg.first); - } - else if (command == COMMAND_THREADSAFE) { - node->setThreadSafeness(Node::ThreadSafe); - } - else if (command == COMMAND_TITLE) { - node->setTitle(arg.first); - if (!node->isDocumentNode() && !node->isCollectionNode()) - location.warning(tr("Ignored '\\%1'").arg(COMMAND_SUBTITLE)); - else if (node->isExample()) - qdb_->addExampleNode(static_cast<ExampleNode*>(node)); - } - else if (command == COMMAND_SUBTITLE) { - node->setSubTitle(arg.first); - if (!node->isDocumentNode() && !node->isCollectionNode()) - location.warning(tr("Ignored '\\%1'").arg(COMMAND_SUBTITLE)); - } - else if (command == COMMAND_QTVARIABLE) { - node->setQtVariable(arg.first); - if (!node->isModule() && !node->isQmlModule()) - location.warning(tr("Command '\\%1' is only meanigfule in '\\module' and '\\qmlmodule'.") - .arg(COMMAND_QTVARIABLE)); - } - else if (command == COMMAND_NOAUTOLIST) { - node->setNoAutoList(true); - } -} - -/*! - \internal - */ -void CodeParser::extractPageLinkAndDesc(const QString& arg, - QString* link, - QString* desc) -{ - QRegExp bracedRegExp(QLatin1String("\\{([^{}]*)\\}(?:\\{([^{}]*)\\})?")); - - if (bracedRegExp.exactMatch(arg)) { - *link = bracedRegExp.cap(1); - *desc = bracedRegExp.cap(2); - if (desc->isEmpty()) - *desc = *link; - } - else { - int spaceAt = arg.indexOf(QLatin1Char(' ')); - if (arg.contains(QLatin1String(".html")) && spaceAt != -1) { - *link = arg.leftRef(spaceAt).trimmed().toString(); - *desc = arg.midRef(spaceAt).trimmed().toString(); - } - else { - *link = arg; - *desc = arg; - } - } -} - -/*! - \internal - */ -void CodeParser::setLink(Node* node, Node::LinkType linkType, const QString& arg) -{ - QString link; - QString desc; - extractPageLinkAndDesc(arg, &link, &desc); - node->setLink(linkType, link, desc); -} - -/*! - Returns \c true if the file being parsed is a .h file. - */ -bool CodeParser::isParsingH() const -{ - return currentFile_.endsWith(".h"); -} - -/*! - Returns \c true if the file being parsed is a .cpp file. - */ -bool CodeParser::isParsingCpp() const -{ - return currentFile_.endsWith(".cpp"); -} - -/*! - Returns \c true if the file being parsed is a .qdoc file. - */ -bool CodeParser::isParsingQdoc() const -{ - return currentFile_.endsWith(".qdoc"); -} - -/*! - For each node that will produce a documentation page, this function - ensures that the node belongs to a module. Normally, the qdoc comment - for an entity that will produce a documentation page will contain an - \inmodule command to tell qdoc which module the entity belongs to. - - But now we normally run qdoc on each module in two passes. The first - produces an index file; the second pass generates the docs after - reading all the index files it needs. - - This means that all the pages generated during each pass 2 run of - qdoc almost certainly belong to a single module, and the name of - that module is, as a rule, used as the project name in the qdocconf - file used when running qdoc on the module. - - So this function first asks if the node \a n has a non-empty module - name. If it it does not have a non-empty module name, it sets the - module name to be the project name. - - In some cases it prints a qdoc warning that it has done this. Namely, - for C++ classes and namespaces. - */ -void CodeParser::checkModuleInclusion(Node* n) -{ - if (n->physicalModuleName().isEmpty()) { - n->setPhysicalModuleName(Generator::defaultModuleName()); - switch (n->type()) { - case Node::Class: - if (n->access() != Node::Private && !n->doc().isEmpty()) { - n->doc().location().warning(tr("Class %1 has no \\inmodule command; " - "using project name by default: %2") - .arg(n->name()).arg(Generator::defaultModuleName())); - } - break; - case Node::Namespace: - if (n->access() != Node::Private && !n->name().isEmpty() && !n->doc().isEmpty()) { - n->doc().location().warning(tr("Namespace %1 has no \\inmodule command; " - "using project name by default: %2") - .arg(n->name()).arg(Generator::defaultModuleName())); - } - break; - default: - break; - } - } -} - -QT_END_NAMESPACE diff --git a/src/tools/qdoc/codeparser.h b/src/tools/qdoc/codeparser.h deleted file mode 100644 index 9d9e9286ec..0000000000 --- a/src/tools/qdoc/codeparser.h +++ /dev/null @@ -1,97 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#ifndef CODEPARSER_H -#define CODEPARSER_H - -#include <qset.h> -#include "node.h" - -QT_BEGIN_NAMESPACE - -class Config; -class QString; -class QDocDatabase; - -class CodeParser -{ - Q_DECLARE_TR_FUNCTIONS(QDoc::CodeParser) - -public: - CodeParser(); - virtual ~CodeParser(); - - virtual void initializeParser(const Config& config); - virtual void terminateParser(); - virtual QString language() = 0; - virtual QStringList headerFileNameFilter(); - virtual QStringList sourceFileNameFilter() = 0; - virtual void parseHeaderFile(const Location& location, const QString& filePath); - virtual void parseSourceFile(const Location& location, const QString& filePath) = 0; - virtual void doneParsingHeaderFiles(); - virtual void doneParsingSourceFiles() = 0; - - bool isParsingH() const; - bool isParsingCpp() const; - bool isParsingQdoc() const; - const QString& currentFile() const { return currentFile_; } - void checkModuleInclusion(Node* n); - - static void initialize(const Config& config); - static void terminate(); - static CodeParser *parserForLanguage(const QString& language); - static CodeParser *parserForHeaderFile(const QString &filePath); - static CodeParser *parserForSourceFile(const QString &filePath); - static void setLink(Node* node, Node::LinkType linkType, const QString& arg); - -protected: - const QSet<QString>& commonMetaCommands(); - void processCommonMetaCommand(const Location& location, - const QString& command, - const ArgLocPair& arg, - Node *node); - static void extractPageLinkAndDesc(const QString& arg, - QString* link, - QString* desc); - QString currentFile_; - QDocDatabase* qdb_; - -private: - static QList<CodeParser *> parsers; - static bool showInternal_; - static bool singleExec_; -}; - -QT_END_NAMESPACE - -#endif diff --git a/src/tools/qdoc/config.cpp b/src/tools/qdoc/config.cpp deleted file mode 100644 index 6c47b86d22..0000000000 --- a/src/tools/qdoc/config.cpp +++ /dev/null @@ -1,1221 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/* - config.cpp -*/ - -#include <qdir.h> -#include <qvariant.h> -#include <qfile.h> -#include <qtemporaryfile.h> -#include <qtextstream.h> -#include <qdebug.h> -#include "config.h" -#include "generator.h" -#include <stdlib.h> - -QT_BEGIN_NAMESPACE - -QString ConfigStrings::ALIAS = QStringLiteral("alias"); -QString ConfigStrings::AUTOLINKERRORS = QStringLiteral("autolinkerrors"); -QString ConfigStrings::BASE = QStringLiteral("base"); -QString ConfigStrings::BASEDIR = QStringLiteral("basedir"); -QString ConfigStrings::BUILDVERSION = QStringLiteral("buildversion"); -QString ConfigStrings::CODEINDENT = QStringLiteral("codeindent"); -QString ConfigStrings::CODEPREFIX = QStringLiteral("codeprefix"); -QString ConfigStrings::CODESUFFIX = QStringLiteral("codesuffix"); -QString ConfigStrings::CPPCLASSESPAGE = QStringLiteral("cppclassespage"); -QString ConfigStrings::DEFINES = QStringLiteral("defines"); -QString ConfigStrings::DEPENDS = QStringLiteral("depends"); -QString ConfigStrings::DESCRIPTION = QStringLiteral("description"); -QString ConfigStrings::EDITION = QStringLiteral("edition"); -QString ConfigStrings::ENDHEADER = QStringLiteral("endheader"); -QString ConfigStrings::EXAMPLEDIRS = QStringLiteral("exampledirs"); -QString ConfigStrings::EXAMPLES = QStringLiteral("examples"); -QString ConfigStrings::EXAMPLESINSTALLPATH = QStringLiteral("examplesinstallpath"); -QString ConfigStrings::EXCLUDEDIRS = QStringLiteral("excludedirs"); -QString ConfigStrings::EXCLUDEFILES = QStringLiteral("excludefiles"); -QString ConfigStrings::EXTRAIMAGES = QStringLiteral("extraimages"); -QString ConfigStrings::FALSEHOODS = QStringLiteral("falsehoods"); -QString ConfigStrings::FORMATTING = QStringLiteral("formatting"); -QString ConfigStrings::GENERATEINDEX = QStringLiteral("generateindex"); -QString ConfigStrings::HEADERDIRS = QStringLiteral("headerdirs"); -QString ConfigStrings::HEADERS = QStringLiteral("headers"); -QString ConfigStrings::HEADERSCRIPTS = QStringLiteral("headerscripts"); -QString ConfigStrings::HEADERSTYLES = QStringLiteral("headerstyles"); -QString ConfigStrings::HOMEPAGE = QStringLiteral("homepage"); -QString ConfigStrings::IGNOREDIRECTIVES = QStringLiteral("ignoredirectives"); -QString ConfigStrings::IGNORETOKENS = QStringLiteral("ignoretokens"); -QString ConfigStrings::IMAGEDIRS = QStringLiteral("imagedirs"); -QString ConfigStrings::IMAGES = QStringLiteral("images"); -QString ConfigStrings::INDEXES = QStringLiteral("indexes"); -QString ConfigStrings::LANDINGPAGE = QStringLiteral("landingpage"); -QString ConfigStrings::LANGUAGE = QStringLiteral("language"); -QString ConfigStrings::MACRO = QStringLiteral("macro"); -QString ConfigStrings::MANIFESTMETA = QStringLiteral("manifestmeta"); -QString ConfigStrings::NATURALLANGUAGE = QStringLiteral("naturallanguage"); -QString ConfigStrings::NAVIGATION = QStringLiteral("navigation"); -QString ConfigStrings::NOLINKERRORS = QStringLiteral("nolinkerrors"); -QString ConfigStrings::OBSOLETELINKS = QStringLiteral("obsoletelinks"); -QString ConfigStrings::OUTPUTDIR = QStringLiteral("outputdir"); -QString ConfigStrings::OUTPUTENCODING = QStringLiteral("outputencoding"); -QString ConfigStrings::OUTPUTLANGUAGE = QStringLiteral("outputlanguage"); -QString ConfigStrings::OUTPUTFORMATS = QStringLiteral("outputformats"); -QString ConfigStrings::OUTPUTPREFIXES = QStringLiteral("outputprefixes"); -QString ConfigStrings::OUTPUTSUFFIXES = QStringLiteral("outputsuffixes"); -QString ConfigStrings::PROJECT = QStringLiteral("project"); -QString ConfigStrings::REDIRECTDOCUMENTATIONTODEVNULL = QStringLiteral("redirectdocumentationtodevnull"); -QString ConfigStrings::QHP = QStringLiteral("qhp"); -QString ConfigStrings::QUOTINGINFORMATION = QStringLiteral("quotinginformation"); -QString ConfigStrings::SCRIPTDIRS = QStringLiteral("scriptdirs"); -QString ConfigStrings::SCRIPTS = QStringLiteral("scripts"); -QString ConfigStrings::SHOWINTERNAL = QStringLiteral("showinternal"); -QString ConfigStrings::SINGLEEXEC = QStringLiteral("singleexec"); -QString ConfigStrings::SOURCEDIRS = QStringLiteral("sourcedirs"); -QString ConfigStrings::SOURCEENCODING = QStringLiteral("sourceencoding"); -QString ConfigStrings::SOURCES = QStringLiteral("sources"); -QString ConfigStrings::SPURIOUS = QStringLiteral("spurious"); -QString ConfigStrings::STYLEDIRS = QStringLiteral("styledirs"); -QString ConfigStrings::STYLE = QStringLiteral("style"); -QString ConfigStrings::STYLES = QStringLiteral("styles"); -QString ConfigStrings::STYLESHEETS = QStringLiteral("stylesheets"); -QString ConfigStrings::SYNTAXHIGHLIGHTING = QStringLiteral("syntaxhighlighting"); -QString ConfigStrings::TEMPLATEDIR = QStringLiteral("templatedir"); -QString ConfigStrings::TABSIZE = QStringLiteral("tabsize"); -QString ConfigStrings::TAGFILE = QStringLiteral("tagfile"); -QString ConfigStrings::TRANSLATORS = QStringLiteral("translators"); -QString ConfigStrings::URL = QStringLiteral("url"); -QString ConfigStrings::VERSION = QStringLiteral("version"); -QString ConfigStrings::VERSIONSYM = QStringLiteral("versionsym"); -QString ConfigStrings::FILEEXTENSIONS = QStringLiteral("fileextensions"); -QString ConfigStrings::IMAGEEXTENSIONS = QStringLiteral("imageextensions"); -QString ConfigStrings::QMLONLY = QStringLiteral("qmlonly"); -QString ConfigStrings::QMLTYPESPAGE = QStringLiteral("qmltypespage"); -QString ConfigStrings::WRITEQAPAGES = QStringLiteral("writeqapages"); - -/*! - An entry in a stack, where each entry is a list - of string values. - */ -class MetaStackEntry -{ -public: - void open(); - void close(); - - QStringList accum; - QStringList next; -}; -Q_DECLARE_TYPEINFO(MetaStackEntry, Q_MOVABLE_TYPE); - -/*! - Start accumulating values in a list by appending an empty - string to the list. - */ -void MetaStackEntry::open() -{ - next.append(QString()); -} - -/*! - Stop accumulating values and append the list of accumulated - values to the complete list of accumulated values. - - */ -void MetaStackEntry::close() -{ - accum += next; - next.clear(); -} - -/*! - \class MetaStack - - This class maintains a stack of values of config file variables. -*/ -class MetaStack : private QStack<MetaStackEntry> -{ - Q_DECLARE_TR_FUNCTIONS(QDoc::MetaStack) - -public: - MetaStack(); - - void process(QChar ch, const Location& location); - QStringList getExpanded(const Location& location); -}; - -/*! - The default constructor pushes a new stack entry and - opens it. - */ -MetaStack::MetaStack() -{ - push(MetaStackEntry()); - top().open(); -} - -/*! - Processes the character \a ch using the \a location. - It really just builds up a name by appending \a ch to - it. - */ -void MetaStack::process(QChar ch, const Location& location) -{ - if (ch == QLatin1Char('{')) { - push(MetaStackEntry()); - top().open(); - } else if (ch == QLatin1Char('}')) { - if (count() == 1) - location.fatal(tr("Unexpected '}'")); - - top().close(); - QStringList suffixes = pop().accum; - QStringList prefixes = top().next; - - top().next.clear(); - QStringList::ConstIterator pre = prefixes.constBegin(); - while (pre != prefixes.constEnd()) { - QStringList::ConstIterator suf = suffixes.constBegin(); - while (suf != suffixes.constEnd()) { - top().next << (*pre + *suf); - ++suf; - } - ++pre; - } - } else if (ch == QLatin1Char(',') && count() > 1) { - top().close(); - top().open(); - } else { - /* - This is where all the processing is done. - */ - QStringList::Iterator pre = top().next.begin(); - while (pre != top().next.end()) { - *pre += ch; - ++pre; - } - } -} - -/*! - Returns the accumulated string values. - */ -QStringList MetaStack::getExpanded(const Location& location) -{ - if (count() > 1) - location.fatal(tr("Missing '}'")); - - top().close(); - return top().accum; -} - -const QString Config::dot = QLatin1String("."); -bool Config::debug_ = false; -bool Config::generateExamples = true; -QString Config::overrideOutputDir; -QString Config::installDir; -QSet<QString> Config::overrideOutputFormats; -QMap<QString, QString> Config::extractedDirs; -int Config::numInstances; -QStack<QString> Config::workingDirs_; -QMap<QString, QStringList> Config::includeFilesMap_; - -/*! - \class Config - \brief The Config class contains the configuration variables - for controlling how qdoc produces documentation. - - Its load() function, reads, parses, and processes a qdocconf file. - */ - -/*! - The constructor sets the \a programName and initializes all - internal state variables to empty values. - */ -Config::Config(const QString& programName) - : prog(programName) -{ - loc = Location::null; - lastLocation_ = Location::null; - configVars_.clear(); - numInstances++; - includeFilesMap_.clear(); -} - -/*! - The destructor has nothing special to do. - */ -Config::~Config() -{ - includeFilesMap_.clear(); -} - -/*! - Loads and parses the qdoc configuration file \a fileName. - This function calls the other load() function, which does - the loading, parsing, and processing of the configuration - file. - - Intializes the location variables returned by location() - and lastLocation(). - */ -void Config::load(const QString& fileName) -{ - load(Location::null, fileName); - if (loc.isEmpty()) - loc = Location(fileName); - else - loc.setEtc(true); - lastLocation_ = Location::null; -} - -/*! - Joins all the strings in \a values into a single string with the - individual \a values separated by ' '. Then it inserts the result - into the string list map with \a var as the key. - - It also inserts the \a values string list into a separate map, - also with \a var as the key. - */ -void Config::setStringList(const QString& var, const QStringList& values) -{ - configVars_.insert(var,ConfigVar(var, values, QDir::currentPath())); -} - -/*! - Looks up the configuarion variable \a var in the string - map and returns the boolean value. - */ -bool Config::getBool(const QString& var) const -{ - return QVariant(getString(var)).toBool(); -} - -/*! - Looks up the configuration variable \a var in the string list - map. Iterates through the string list found, interpreting each - string in the list as an integer and adding it to a total sum. - Returns the sum or \c -1 if \a var is not set. - */ -int Config::getInt(const QString& var) const -{ - QStringList strs = getStringList(var); - if (strs.isEmpty()) - return -1; - - QStringList::ConstIterator s = strs.constBegin(); - int sum = 0; - - while (s != strs.constEnd()) { - sum += (*s).toInt(); - ++s; - } - return sum; -} - -/*! - Function to return the correct outputdir. - outputdir can be set using the qdocconf or the command-line - variable -outputdir. - */ -QString Config::getOutputDir() const -{ - QString t; - if (overrideOutputDir.isNull()) - t = getString(CONFIG_OUTPUTDIR); - else - t = overrideOutputDir; - if (Generator::singleExec()) { - QString project = getString(CONFIG_PROJECT); - t += QLatin1Char('/') + project.toLower(); - } - if (!Generator::useOutputSubdirs()) { - t = t.left(t.lastIndexOf('/')); - QString singleOutputSubdir = getString("HTML.outputsubdir"); - if (singleOutputSubdir.isEmpty()) - singleOutputSubdir = "html"; - t += QLatin1Char('/') + singleOutputSubdir; - } - return t; -} - -/*! - Function to return the correct outputformats. - outputformats can be set using the qdocconf or the command-line - variable -outputformat. - */ -QSet<QString> Config::getOutputFormats() const -{ - if (overrideOutputFormats.isEmpty()) - return getStringSet(CONFIG_OUTPUTFORMATS); - else - return overrideOutputFormats; -} - -/*! - First, this function looks up the configuration variable \a var - in the location map and, if found, sets the internal variable - \c{lastLocation_} to the Location that \a var maps to. - - Then it looks up the configuration variable \a var in the string - map and returns the string that \a var maps to. - */ -QString Config::getString(const QString& var) const -{ - QList<ConfigVar> configVars = configVars_.values(var); - QString value; - if (!configVars.empty()) { - int i = configVars.size() - 1; - while (i >= 0) { - const ConfigVar& cv = configVars[i]; - if (!cv.location_.isEmpty()) - const_cast<Config *>(this)->lastLocation_ = cv.location_; - if (!cv.values_.isEmpty()) { - if (!cv.plus_) - value.clear(); - for (int j=0; j<cv.values_.size(); ++j) { - if (!value.isEmpty() && !value.endsWith(QChar('\n'))) - value.append(QChar(' ')); - value.append(cv.values_[j]); - } - } - --i; - } - } - return value; -} - -/*! - Looks up the configuration variable \a var in the string - list map, converts the string list it maps to into a set - of strings, and returns the set. - */ -QSet<QString> Config::getStringSet(const QString& var) const -{ - return QSet<QString>::fromList(getStringList(var)); -} - -/*! - First, this function looks up the configuration variable \a var - in the location map. If found, it sets the internal variable - \c{lastLocation_} to the Location that \a var maps to. - - Then it looks up the configuration variable \a var in the map of - configuration variable records. If found, it gets a list of all - the records for \a var. Then it appends all the values for \a var - to a list and returns the list. As it appends the values from each - record, if the \a var used '=' instead of '+=' the list is cleared - before the values are appended. \note '+=' should always be used. - The final list is returned. - */ -QStringList Config::getStringList(const QString& var) const -{ - QList<ConfigVar> configVars = configVars_.values(var); - QStringList values; - if (!configVars.empty()) { - int i = configVars.size() - 1; - while (i >= 0) { - if (!configVars[i].location_.isEmpty()) - const_cast<Config *>(this)->lastLocation_ = configVars[i].location_; - if (configVars[i].plus_) - values.append(configVars[i].values_); - else - values = configVars[i].values_; - --i; - } - } - return values; -} - -/*! - Returns the a path list where all paths from the config variable \a var - are canonicalized. If \a validate is true, a warning for invalid paths is - generated. - - First, this function looks up the configuration variable \a var - in the location map and, if found, sets the internal variable - \c{lastLocation_} the Location that \a var maps to. - - Then it looks up the configuration variable \a var in the string - list map, which maps to one or more records that each contains a - list of file paths. - - \sa Location::canonicalRelativePath() - */ -QStringList Config::getCanonicalPathList(const QString& var, bool validate) const -{ - QStringList t; - QList<ConfigVar> configVars = configVars_.values(var); - if (!configVars.empty()) { - int i = configVars.size() - 1; - while (i >= 0) { - const ConfigVar& cv = configVars[i]; - if (!cv.location_.isEmpty()) - const_cast<Config *>(this)->lastLocation_ = cv.location_; - if (!cv.plus_) - t.clear(); - const QString d = cv.currentPath_; - const QStringList& sl = cv.values_; - if (!sl.isEmpty()) { - t.reserve(t.size() + sl.size()); - for (int i=0; i<sl.size(); ++i) { - QDir dir(sl[i].simplified()); - QString path = dir.path(); - if (dir.isRelative()) - dir.setPath(d + QLatin1Char('/') + path); - if (validate && !QFileInfo::exists(dir.path())) - lastLocation_.warning(tr("Cannot find file or directory: %1").arg(path)); - else - t.append(dir.canonicalPath()); - } - } - --i; - } - } - return t; -} - -/*! - Calls getRegExpList() with the control variable \a var and - iterates through the resulting list of regular expressions, - concatening them with some extras characters to form a single - QRegExp, which is returned/ - - \sa getRegExpList() - */ -QRegExp Config::getRegExp(const QString& var) const -{ - QString pattern; - QList<QRegExp> subRegExps = getRegExpList(var); - QList<QRegExp>::ConstIterator s = subRegExps.constBegin(); - - while (s != subRegExps.constEnd()) { - if (!(*s).isValid()) - return *s; - if (!pattern.isEmpty()) - pattern += QLatin1Char('|'); - pattern += QLatin1String("(?:") + (*s).pattern() + QLatin1Char(')'); - ++s; - } - if (pattern.isEmpty()) - pattern = QLatin1String("$x"); // cannot match - return QRegExp(pattern); -} - -/*! - Looks up the configuration variable \a var in the string list - map, converts the string list to a list of regular expressions, - and returns it. - */ -QList<QRegExp> Config::getRegExpList(const QString& var) const -{ - QStringList strs = getStringList(var); - QStringList::ConstIterator s = strs.constBegin(); - QList<QRegExp> regExps; - - while (s != strs.constEnd()) { - regExps += QRegExp(*s); - ++s; - } - return regExps; -} - -/*! - This function is slower than it could be. What it does is - find all the keys that begin with \a var + dot and return - the matching keys in a set, stripped of the matching prefix - and dot. - */ -QSet<QString> Config::subVars(const QString& var) const -{ - QSet<QString> result; - QString varDot = var + QLatin1Char('.'); - ConfigVarMultimap::ConstIterator i = configVars_.constBegin(); - while (i != configVars_.constEnd()) { - if (i.key().startsWith(varDot)) { - QString subVar = i.key().mid(varDot.length()); - int dot = subVar.indexOf(QLatin1Char('.')); - if (dot != -1) - subVar.truncate(dot); - if (!result.contains(subVar)) - result.insert(subVar); - } - ++i; - } - return result; -} - -/*! - Same as subVars(), but in this case we return a config var - multimap with the matching keys (stripped of the prefix \a var - and mapped to their values. The pairs are inserted into \a t - */ -void Config::subVarsAndValues(const QString& var, ConfigVarMultimap& t) const -{ - QString varDot = var + QLatin1Char('.'); - ConfigVarMultimap::ConstIterator v = configVars_.constBegin(); - while (v != configVars_.constEnd()) { - if (v.key().startsWith(varDot)) { - QString subVar = v.key().mid(varDot.length()); - int dot = subVar.indexOf(QLatin1Char('.')); - if (dot != -1) - subVar.truncate(dot); - t.insert(subVar,v.value()); - } - ++v; - } -} - -/*! - Get all .qdocinc files. - */ -QString Config::getIncludeFilePath(const QString& fileName) const -{ - QString ext = fileName.mid(fileName.lastIndexOf('.')); - ext.prepend('*'); - - if (!includeFilesMap_.contains(ext)) { - QSet<QString> t; - QStringList result; - QStringList dirs = getCanonicalPathList(CONFIG_SOURCEDIRS); - QStringList::ConstIterator d = dirs.constBegin(); - while (d != dirs.constEnd()) { - result += getFilesHere(*d, ext, location(), t, t); - ++d; - } - includeFilesMap_.insert(ext, result); - } - const QStringList& paths = (*includeFilesMap_.find(ext)); - for (int i=0; i<paths.size(); ++i) { - if (paths[i].endsWith(fileName)) - return paths[i]; - } - return QString(); -} - -/*! - Builds and returns a list of file pathnames for the file - type specified by \a filesVar (e.g. "headers" or "sources"). - The files are found in the directories specified by - \a dirsVar, and they are filtered by \a defaultNameFilter - if a better filter can't be constructed from \a filesVar. - The directories in \a excludedDirs are avoided. The files - in \a excludedFiles are not included in the return list. - */ -QStringList Config::getAllFiles(const QString &filesVar, - const QString &dirsVar, - const QSet<QString> &excludedDirs, - const QSet<QString> &excludedFiles) -{ - QStringList result = getCanonicalPathList(filesVar); - QStringList dirs = getCanonicalPathList(dirsVar); - - QString nameFilter = getString(filesVar + dot + CONFIG_FILEEXTENSIONS); - - QStringList::ConstIterator d = dirs.constBegin(); - while (d != dirs.constEnd()) { - result += getFilesHere(*d, nameFilter, location(), excludedDirs, excludedFiles); - ++d; - } - return result; -} - -QStringList Config::getExampleQdocFiles(const QSet<QString> &excludedDirs, - const QSet<QString> &excludedFiles) -{ - QStringList result; - QStringList dirs = getCanonicalPathList("exampledirs"); - QString nameFilter = " *.qdoc"; - - QStringList::ConstIterator d = dirs.constBegin(); - while (d != dirs.constEnd()) { - result += getFilesHere(*d, nameFilter, location(), excludedDirs, excludedFiles); - ++d; - } - return result; -} - -QStringList Config::getExampleImageFiles(const QSet<QString> &excludedDirs, - const QSet<QString> &excludedFiles) -{ - QStringList result; - QStringList dirs = getCanonicalPathList("exampledirs"); - QString nameFilter = getString(CONFIG_EXAMPLES + dot + CONFIG_IMAGEEXTENSIONS); - - QStringList::ConstIterator d = dirs.constBegin(); - while (d != dirs.constEnd()) { - result += getFilesHere(*d, nameFilter, location(), excludedDirs, excludedFiles); - ++d; - } - return result; -} - -/*! - \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, - const QStringList& dirs, - const QString& fileName, - QString& userFriendlyFilePath) -{ - if (fileName.isEmpty() || fileName.startsWith(QLatin1Char('/'))) { - userFriendlyFilePath = fileName; - return fileName; - } - - QFileInfo fileInfo; - QStringList components = fileName.split(QLatin1Char('?')); - QString firstComponent = components.first(); - - QStringList::ConstIterator f = files.constBegin(); - while (f != files.constEnd()) { - if (*f == firstComponent || - (*f).endsWith(QLatin1Char('/') + firstComponent)) { - fileInfo.setFile(*f); - if (!fileInfo.exists()) - location.fatal(tr("File '%1' does not exist").arg(*f)); - break; - } - ++f; - } - - if (fileInfo.fileName().isEmpty()) { - QStringList::ConstIterator d = dirs.constBegin(); - while (d != dirs.constEnd()) { - fileInfo.setFile(QDir(*d), firstComponent); - if (fileInfo.exists()) - break; - ++d; - } - } - - userFriendlyFilePath = QString(); - if (!fileInfo.exists()) - return QString(); - - QStringList::ConstIterator c = components.constBegin(); - for (;;) { - bool isArchive = (c != components.constEnd() - 1); - QString userFriendly = *c; - - userFriendlyFilePath += userFriendly; - - if (isArchive) { - QString extracted = extractedDirs[fileInfo.filePath()]; - ++c; - fileInfo.setFile(QDir(extracted), *c); - } else { - break; - } - - userFriendlyFilePath += QLatin1Char('?'); - } - return fileInfo.filePath(); -} - -/*! - */ -QString Config::findFile(const Location& location, - const QStringList& files, - const QStringList& dirs, - const QString& fileBase, - const QStringList& fileExtensions, - QString& userFriendlyFilePath) -{ - QStringList::ConstIterator e = fileExtensions.constBegin(); - while (e != fileExtensions.constEnd()) { - QString filePath = findFile(location, - files, - dirs, - fileBase + QLatin1Char('.') + *e, - userFriendlyFilePath); - if (!filePath.isEmpty()) - return filePath; - ++e; - } - return findFile(location, files, dirs, fileBase, userFriendlyFilePath); -} - -/*! - Copies the \a sourceFilePath to the file name constructed by - concatenating \a targetDirPath and the file name from the - \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, - const QString& userFriendlySourceFilePath, - const QString& targetDirPath) -{ - QFile inFile(sourceFilePath); - if (!inFile.open(QFile::ReadOnly)) { - location.warning(tr("Cannot open input file for copy: '%1': %2") - .arg(sourceFilePath).arg(inFile.errorString())); - return QString(); - } - - QString outFileName = userFriendlySourceFilePath; - int slash = outFileName.lastIndexOf(QLatin1Char('/')); - if (slash != -1) - outFileName = outFileName.mid(slash); - if ((outFileName.size()) > 0 && (outFileName[0] != '/')) - outFileName = targetDirPath + QLatin1Char('/') + outFileName; - else - outFileName = targetDirPath + outFileName; - QFile outFile(outFileName); - if (!outFile.open(QFile::WriteOnly)) { - location.warning(tr("Cannot open output file for copy: '%1': %2") - .arg(outFileName).arg(outFile.errorString())); - return QString(); - } - - char buffer[1024]; - int len; - while ((len = inFile.read(buffer, sizeof(buffer))) > 0) - outFile.write(buffer, len); - return outFileName; -} - -/*! - Finds the largest unicode digit in \a value in the range - 1..7 and returns it. - */ -int Config::numParams(const QString& value) -{ - int max = 0; - for (int i = 0; i != value.length(); i++) { - uint c = value[i].unicode(); - if (c > 0 && c < 8) - max = qMax(max, (int)c); - } - return max; -} - -/*! - Removes everything from \a dir. This function is recursive. - It doesn't remove \a dir itself, but if it was called - recursively, then the caller will remove \a dir. - */ -bool Config::removeDirContents(const QString& dir) -{ - QDir dirInfo(dir); - QFileInfoList entries = dirInfo.entryInfoList(); - - bool ok = true; - - QFileInfoList::Iterator it = entries.begin(); - while (it != entries.end()) { - if ((*it).isFile()) { - if (!dirInfo.remove((*it).fileName())) - ok = false; - } - else if ((*it).isDir()) { - if ((*it).fileName() != QLatin1String(".") && (*it).fileName() != QLatin1String("..")) { - if (removeDirContents((*it).absoluteFilePath())) { - if (!dirInfo.rmdir((*it).fileName())) - ok = false; - } - else { - ok = false; - } - } - } - ++it; - } - return ok; -} - -/*! - Returns \c true if \a ch is a letter, number, '_', '.', - '{', '}', or ','. - */ -bool Config::isMetaKeyChar(QChar ch) -{ - return ch.isLetterOrNumber() - || ch == QLatin1Char('_') - || ch == QLatin1Char('.') - || ch == QLatin1Char('{') - || ch == QLatin1Char('}') - || ch == QLatin1Char(','); -} - -/*! - \a fileName is a master qdocconf file. It contains a list of - qdocconf files and nothing else. Read the list and return it. - */ -QStringList Config::loadMaster(const QString& fileName) -{ - Location location = Location::null; - QFile fin(fileName); - if (!fin.open(QFile::ReadOnly | QFile::Text)) { - if (!Config::installDir.isEmpty()) { - int prefix = location.filePath().length() - location.fileName().length(); - fin.setFileName(Config::installDir + QLatin1Char('/') + fileName.right(fileName.length() - prefix)); - } - if (!fin.open(QFile::ReadOnly | QFile::Text)) - location.fatal(tr("Cannot open master qdocconf file '%1': %2").arg(fileName).arg(fin.errorString())); - } - QTextStream stream(&fin); -#ifndef QT_NO_TEXTCODEC - stream.setCodec("UTF-8"); -#endif - QStringList qdocFiles; - QString line = stream.readLine(); - while (!line.isNull()) { - qdocFiles.append(line); - line = stream.readLine(); - } - fin.close(); - return qdocFiles; -} - -/*! - Load, parse, and process a qdoc configuration file. This - function is only called by the other load() function, but - this one is recursive, i.e., it calls itself when it sees - an \c{include} statement in the qdoc configuration file. - */ -void Config::load(Location location, const QString& fileName) -{ - QFileInfo fileInfo(fileName); - QString path = fileInfo.canonicalPath(); - pushWorkingDir(path); - QDir::setCurrent(path); - QRegExp keySyntax(QLatin1String("\\w+(?:\\.\\w+)*")); - -#define SKIP_CHAR() \ - do { \ - location.advance(c); \ - ++i; \ - c = text.at(i); \ - cc = c.unicode(); \ -} while (0) - -#define SKIP_SPACES() \ - while (c.isSpace() && cc != '\n') \ - SKIP_CHAR() - -#define PUT_CHAR() \ - word += c; \ - SKIP_CHAR(); - - if (location.depth() > 16) - location.fatal(tr("Too many nested includes")); - - QFile fin(fileInfo.fileName()); - if (!fin.open(QFile::ReadOnly | QFile::Text)) { - if (!Config::installDir.isEmpty()) { - int prefix = location.filePath().length() - location.fileName().length(); - fin.setFileName(Config::installDir + QLatin1Char('/') + fileName.right(fileName.length() - prefix)); - } - if (!fin.open(QFile::ReadOnly | QFile::Text)) - location.fatal(tr("Cannot open file '%1': %2").arg(fileName).arg(fin.errorString())); - } - - QTextStream stream(&fin); -#ifndef QT_NO_TEXTCODEC - stream.setCodec("UTF-8"); -#endif - QString text = stream.readAll(); - text += QLatin1String("\n\n"); - text += QLatin1Char('\0'); - fin.close(); - - location.push(fileName); - location.start(); - - int i = 0; - QChar c = text.at(0); - uint cc = c.unicode(); - while (i < (int) text.length()) { - if (cc == 0) { - ++i; - } else if (c.isSpace()) { - SKIP_CHAR(); - } else if (cc == '#') { - do { - SKIP_CHAR(); - } while (cc != '\n'); - } else if (isMetaKeyChar(c)) { - Location keyLoc = location; - bool plus = false; - QString stringValue; - QStringList rhsValues; - QString word; - bool inQuote = false; - bool prevWordQuoted = true; - bool metWord = false; - - MetaStack stack; - do { - stack.process(c, location); - SKIP_CHAR(); - } while (isMetaKeyChar(c)); - - QStringList keys = stack.getExpanded(location); - SKIP_SPACES(); - - if (keys.count() == 1 && keys.first() == QLatin1String("include")) { - QString includeFile; - - if (cc != '(') - location.fatal(tr("Bad include syntax")); - SKIP_CHAR(); - SKIP_SPACES(); - - while (!c.isSpace() && cc != '#' && cc != ')') { - - if (cc == '$') { - QString var; - SKIP_CHAR(); - while (c.isLetterOrNumber() || cc == '_') { - var += c; - SKIP_CHAR(); - } - if (!var.isEmpty()) { - const QByteArray val = qgetenv(var.toLatin1().data()); - if (val.isNull()) { - location.fatal(tr("Environment variable '%1' undefined").arg(var)); - } - else { - includeFile += QString::fromLatin1(val); - } - } - } else { - includeFile += c; - SKIP_CHAR(); - } - } - SKIP_SPACES(); - if (cc != ')') - location.fatal(tr("Bad include syntax")); - SKIP_CHAR(); - SKIP_SPACES(); - if (cc != '#' && cc != '\n') - location.fatal(tr("Trailing garbage")); - - /* - Here is the recursive call. - */ - load(location, QFileInfo(QDir(path), includeFile).filePath()); - } - else { - /* - It wasn't an include statement, so it's something else. - We must see either '=' or '+=' next. If not, fatal error. - */ - if (cc == '+') { - plus = true; - SKIP_CHAR(); - } - if (cc != '=') - location.fatal(tr("Expected '=' or '+=' after key")); - SKIP_CHAR(); - SKIP_SPACES(); - - for (;;) { - if (cc == '\\') { - int metaCharPos; - - SKIP_CHAR(); - if (cc == '\n') { - SKIP_CHAR(); - } - else if (cc > '0' && cc < '8') { - word += QChar(c.digitValue()); - SKIP_CHAR(); - } - else if ((metaCharPos = QString::fromLatin1("abfnrtv").indexOf(c)) != -1) { - word += QLatin1Char("\a\b\f\n\r\t\v"[metaCharPos]); - SKIP_CHAR(); - } - else { - PUT_CHAR(); - } - } - else if (c.isSpace() || cc == '#') { - if (inQuote) { - if (cc == '\n') - location.fatal(tr("Unterminated string")); - PUT_CHAR(); - } - else { - if (!word.isEmpty()) { - if (metWord) - stringValue += QLatin1Char(' '); - stringValue += word; -#if 0 - if (metWord) - rhsValues << QString(" " + word); - else -#endif - rhsValues << word; - metWord = true; - word.clear(); - prevWordQuoted = false; - } - if (cc == '\n' || cc == '#') - break; - SKIP_SPACES(); - } - } - else if (cc == '"') { - if (inQuote) { - if (!prevWordQuoted) - stringValue += QLatin1Char(' '); - stringValue += word; - if (!word.isEmpty()) - rhsValues << word; - metWord = true; - word.clear(); - prevWordQuoted = true; - } - inQuote = !inQuote; - SKIP_CHAR(); - } - else if (cc == '$') { - QString var; - SKIP_CHAR(); - while (c.isLetterOrNumber() || cc == '_') { - var += c; - SKIP_CHAR(); - } - if (!var.isEmpty()) { - const QByteArray val = qgetenv(var.toLatin1().constData()); - if (val.isNull()) { - location.fatal(tr("Environment variable '%1' undefined").arg(var)); - } - else { - word += QString::fromLatin1(val); - } - } - } - else { - if (!inQuote && cc == '=') - location.fatal(tr("Unexpected '='")); - PUT_CHAR(); - } - } - - QStringList::ConstIterator key = keys.constBegin(); - while (key != keys.constEnd()) { - if (!keySyntax.exactMatch(*key)) - keyLoc.fatal(tr("Invalid key '%1'").arg(*key)); - - ConfigVarMultimap::Iterator i; - i = configVars_.insert(*key, ConfigVar(*key, rhsValues, QDir::currentPath(), keyLoc)); - i.value().plus_ = plus; - ++key; - } - } - } else { - location.fatal(tr("Unexpected character '%1' at beginning of line").arg(c)); - } - } - popWorkingDir(); - if (!workingDirs_.isEmpty()) - QDir::setCurrent(workingDirs_.top()); -} - -QStringList Config::getFilesHere(const QString& uncleanDir, - const QString& nameFilter, - const Location &location, - const QSet<QString> &excludedDirs, - const QSet<QString> &excludedFiles) -{ - QString dir = location.isEmpty() ? QDir::cleanPath(uncleanDir) : QDir(uncleanDir).canonicalPath(); - QStringList result; - if (excludedDirs.contains(dir)) - return result; - - QDir dirInfo(dir); - QStringList fileNames; - QStringList::const_iterator fn; - - dirInfo.setNameFilters(nameFilter.split(QLatin1Char(' '))); - dirInfo.setSorting(QDir::Name); - dirInfo.setFilter(QDir::Files); - fileNames = dirInfo.entryList(); - fn = fileNames.constBegin(); - while (fn != fileNames.constEnd()) { - if (!fn->startsWith(QLatin1Char('~'))) { - QString s = dirInfo.filePath(*fn); - QString c = QDir::cleanPath(s); - if (!excludedFiles.contains(c)) - result.append(c); - } - ++fn; - } - - dirInfo.setNameFilters(QStringList(QLatin1String("*"))); - dirInfo.setFilter(QDir::Dirs|QDir::NoDotAndDotDot); - fileNames = dirInfo.entryList(); - fn = fileNames.constBegin(); - while (fn != fileNames.constEnd()) { - result += getFilesHere(dirInfo.filePath(*fn), nameFilter, location, excludedDirs, excludedFiles); - ++fn; - } - return result; -} - -/*! - Push \a dir onto the stack of working directories. - */ -void Config::pushWorkingDir(const QString& dir) -{ - workingDirs_.push(dir); -} - -/*! - If the stack of working directories is not empty, pop the - top entry and return it. Otherwise return an empty string. - */ -QString Config::popWorkingDir() -{ - if (!workingDirs_.isEmpty()) - return workingDirs_.pop(); - - qDebug() << "RETURNED EMPTY WORKING DIR"; - return QString(); -} - -QT_END_NAMESPACE diff --git a/src/tools/qdoc/config.h b/src/tools/qdoc/config.h deleted file mode 100644 index 740568ca0c..0000000000 --- a/src/tools/qdoc/config.h +++ /dev/null @@ -1,319 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/* - config.h -*/ - -#ifndef CONFIG_H -#define CONFIG_H - -#include <qmap.h> -#include <qset.h> -#include <qstringlist.h> -#include <qstack.h> -#include <qpair.h> -#include "location.h" - -QT_BEGIN_NAMESPACE - -/* - This struct contains all the information for - one config variable found in a qdocconf file. - */ -struct ConfigVar { - bool plus_; - QString name_; - QStringList values_; - QString currentPath_; - Location location_; - - ConfigVar() : plus_(false) { } - - ConfigVar(const QString& name, const QStringList& values, const QString& dir) - : plus_(true), name_(name), values_(values), currentPath_(dir) { } - - ConfigVar(const QString& name, const QStringList& values, const QString& dir, const Location& loc) - : plus_(false), name_(name), values_(values), currentPath_(dir), location_(loc) { } -}; - -/* - In this multimap, the key is a config variable name. - */ -typedef QMultiMap<QString, ConfigVar> ConfigVarMultimap; - -class Config -{ - Q_DECLARE_TR_FUNCTIONS(QDoc::Config) - -public: - Config(const QString& programName); - ~Config(); - - static bool debug_; - - void load(const QString& fileName); - void setStringList(const QString& var, const QStringList& values); - - const QString& programName() const { return prog; } - const Location& location() const { return loc; } - const Location& lastLocation() const { return lastLocation_; } - bool getBool(const QString& var) const; - int getInt(const QString& var) const; - QString getOutputDir() const; - QSet<QString> getOutputFormats() const; - QString getString(const QString& var) const; - QSet<QString> getStringSet(const QString& var) const; - QStringList getStringList(const QString& var) const; - QStringList getCanonicalPathList(const QString& var, bool validate = false) const; - QRegExp getRegExp(const QString& var) const; - QList<QRegExp> getRegExpList(const QString& var) const; - QSet<QString> subVars(const QString& var) const; - void subVarsAndValues(const QString& var, ConfigVarMultimap& t) const; - QStringList getAllFiles(const QString& filesVar, - const QString& dirsVar, - const QSet<QString> &excludedDirs = QSet<QString>(), - const QSet<QString> &excludedFiles = QSet<QString>()); - QString getIncludeFilePath(const QString& fileName) const; - QStringList getExampleQdocFiles(const QSet<QString> &excludedDirs, const QSet<QString> &excludedFiles); - QStringList getExampleImageFiles(const QSet<QString> &excludedDirs, const QSet<QString> &excludedFiles); - - static QStringList loadMaster(const QString& fileName); - static QStringList getFilesHere(const QString& dir, - const QString& nameFilter, - const Location &location = Location(), - const QSet<QString> &excludedDirs = QSet<QString>(), - const QSet<QString> &excludedFiles = QSet<QString>()); - static QString findFile(const Location& location, - const QStringList &files, - const QStringList& dirs, - const QString& fileName, - QString& userFriendlyFilePath); - static QString findFile(const Location &location, - const QStringList &files, - const QStringList &dirs, - const QString &fileBase, - const QStringList &fileExtensions, - QString &userFriendlyFilePath); - static QString copyFile(const Location& location, - const QString& sourceFilePath, - const QString& userFriendlySourceFilePath, - const QString& targetDirPath); - static int numParams(const QString& value); - static bool removeDirContents(const QString& dir); - static void pushWorkingDir(const QString& dir); - static QString popWorkingDir(); - - static const QString dot; - - static bool generateExamples; - static QString installDir; - static QString overrideOutputDir; - static QSet<QString> overrideOutputFormats; - -private: - static bool isMetaKeyChar(QChar ch); - void load(Location location, const QString& fileName); - - QString prog; - Location loc; - Location lastLocation_; - ConfigVarMultimap configVars_; - - static QMap<QString, QString> uncompressedFiles; - static QMap<QString, QString> extractedDirs; - static int numInstances; - static QStack<QString> workingDirs_; - static QMap<QString, QStringList> includeFilesMap_; -}; - -struct ConfigStrings -{ - static QString ALIAS; - static QString AUTOLINKERRORS; - static QString BASE; - static QString BASEDIR; - static QString BUILDVERSION; - static QString CODEINDENT; - static QString CODEPREFIX; - static QString CODESUFFIX; - static QString CPPCLASSESPAGE; - static QString DEFINES; - static QString DEPENDS; - static QString DESCRIPTION; - static QString EDITION; - static QString ENDHEADER; - static QString EXAMPLEDIRS; - static QString EXAMPLES; - static QString EXAMPLESINSTALLPATH; - static QString EXCLUDEDIRS; - static QString EXCLUDEFILES; - static QString EXTRAIMAGES; - static QString FALSEHOODS; - static QString FORMATTING; - static QString GENERATEINDEX; - static QString HEADERDIRS; - static QString HEADERS; - static QString HEADERSCRIPTS; - static QString HEADERSTYLES; - static QString HOMEPAGE; - static QString IGNOREDIRECTIVES; - static QString IGNORETOKENS; - static QString IMAGEDIRS; - static QString IMAGES; - static QString INDEXES; - static QString LANDINGPAGE; - static QString LANGUAGE; - static QString MACRO; - static QString MANIFESTMETA; - static QString NATURALLANGUAGE; - static QString NAVIGATION; - static QString NOLINKERRORS; - static QString OBSOLETELINKS; - static QString OUTPUTDIR; - static QString OUTPUTENCODING; - static QString OUTPUTLANGUAGE; - static QString OUTPUTFORMATS; - static QString OUTPUTPREFIXES; - static QString OUTPUTSUFFIXES; - static QString PROJECT; - static QString REDIRECTDOCUMENTATIONTODEVNULL; - static QString QHP; - static QString QUOTINGINFORMATION; - static QString SCRIPTDIRS; - static QString SCRIPTS; - static QString SHOWINTERNAL; - static QString SINGLEEXEC; - static QString SOURCEDIRS; - static QString SOURCEENCODING; - static QString SOURCES; - static QString SPURIOUS; - static QString STYLEDIRS; - static QString STYLE; - static QString STYLES; - static QString STYLESHEETS; - static QString SYNTAXHIGHLIGHTING; - static QString TEMPLATEDIR; - static QString TABSIZE; - static QString TAGFILE; - static QString TRANSLATORS; - static QString URL; - static QString VERSION; - static QString VERSIONSYM; - static QString FILEEXTENSIONS; - static QString IMAGEEXTENSIONS; - static QString QMLONLY; - static QString QMLTYPESPAGE; - static QString WRITEQAPAGES; -}; - -#define CONFIG_ALIAS ConfigStrings::ALIAS -#define CONFIG_AUTOLINKERRORS ConfigStrings::AUTOLINKERRORS -#define CONFIG_BASE ConfigStrings::BASE -#define CONFIG_BASEDIR ConfigStrings::BASEDIR -#define CONFIG_BUILDVERSION ConfigStrings::BUILDVERSION -#define CONFIG_CODEINDENT ConfigStrings::CODEINDENT -#define CONFIG_CODEPREFIX ConfigStrings::CODEPREFIX -#define CONFIG_CODESUFFIX ConfigStrings::CODESUFFIX -#define CONFIG_CPPCLASSESPAGE ConfigStrings::CPPCLASSESPAGE -#define CONFIG_DEFINES ConfigStrings::DEFINES -#define CONFIG_DEPENDS ConfigStrings::DEPENDS -#define CONFIG_DESCRIPTION ConfigStrings::DESCRIPTION -#define CONFIG_EDITION ConfigStrings::EDITION -#define CONFIG_ENDHEADER ConfigStrings::ENDHEADER -#define CONFIG_EXAMPLEDIRS ConfigStrings::EXAMPLEDIRS -#define CONFIG_EXAMPLES ConfigStrings::EXAMPLES -#define CONFIG_EXAMPLESINSTALLPATH ConfigStrings::EXAMPLESINSTALLPATH -#define CONFIG_EXCLUDEDIRS ConfigStrings::EXCLUDEDIRS -#define CONFIG_EXCLUDEFILES ConfigStrings::EXCLUDEFILES -#define CONFIG_EXTRAIMAGES ConfigStrings::EXTRAIMAGES -#define CONFIG_FALSEHOODS ConfigStrings::FALSEHOODS -#define CONFIG_FORMATTING ConfigStrings::FORMATTING -#define CONFIG_GENERATEINDEX ConfigStrings::GENERATEINDEX -#define CONFIG_HEADERDIRS ConfigStrings::HEADERDIRS -#define CONFIG_HEADERS ConfigStrings::HEADERS -#define CONFIG_HEADERSCRIPTS ConfigStrings::HEADERSCRIPTS -#define CONFIG_HEADERSTYLES ConfigStrings::HEADERSTYLES -#define CONFIG_HOMEPAGE ConfigStrings::HOMEPAGE -#define CONFIG_IGNOREDIRECTIVES ConfigStrings::IGNOREDIRECTIVES -#define CONFIG_IGNORETOKENS ConfigStrings::IGNORETOKENS -#define CONFIG_IMAGEDIRS ConfigStrings::IMAGEDIRS -#define CONFIG_IMAGES ConfigStrings::IMAGES -#define CONFIG_INDEXES ConfigStrings::INDEXES -#define CONFIG_LANDINGPAGE ConfigStrings::LANDINGPAGE -#define CONFIG_LANGUAGE ConfigStrings::LANGUAGE -#define CONFIG_MACRO ConfigStrings::MACRO -#define CONFIG_MANIFESTMETA ConfigStrings::MANIFESTMETA -#define CONFIG_NATURALLANGUAGE ConfigStrings::NATURALLANGUAGE -#define CONFIG_NAVIGATION ConfigStrings::NAVIGATION -#define CONFIG_NOLINKERRORS ConfigStrings::NOLINKERRORS -#define CONFIG_OBSOLETELINKS ConfigStrings::OBSOLETELINKS -#define CONFIG_OUTPUTDIR ConfigStrings::OUTPUTDIR -#define CONFIG_OUTPUTENCODING ConfigStrings::OUTPUTENCODING -#define CONFIG_OUTPUTLANGUAGE ConfigStrings::OUTPUTLANGUAGE -#define CONFIG_OUTPUTFORMATS ConfigStrings::OUTPUTFORMATS -#define CONFIG_OUTPUTPREFIXES ConfigStrings::OUTPUTPREFIXES -#define CONFIG_OUTPUTSUFFIXES ConfigStrings::OUTPUTSUFFIXES -#define CONFIG_PROJECT ConfigStrings::PROJECT -#define CONFIG_REDIRECTDOCUMENTATIONTODEVNULL ConfigStrings::REDIRECTDOCUMENTATIONTODEVNULL -#define CONFIG_QHP ConfigStrings::QHP -#define CONFIG_QUOTINGINFORMATION ConfigStrings::QUOTINGINFORMATION -#define CONFIG_SCRIPTDIRS ConfigStrings::SCRIPTDIRS -#define CONFIG_SCRIPTS ConfigStrings::SCRIPTS -#define CONFIG_SHOWINTERNAL ConfigStrings::SHOWINTERNAL -#define CONFIG_SINGLEEXEC ConfigStrings::SINGLEEXEC -#define CONFIG_SOURCEDIRS ConfigStrings::SOURCEDIRS -#define CONFIG_SOURCEENCODING ConfigStrings::SOURCEENCODING -#define CONFIG_SOURCES ConfigStrings::SOURCES -#define CONFIG_SPURIOUS ConfigStrings::SPURIOUS -#define CONFIG_STYLEDIRS ConfigStrings::STYLEDIRS -#define CONFIG_STYLE ConfigStrings::STYLE -#define CONFIG_STYLES ConfigStrings::STYLES -#define CONFIG_STYLESHEETS ConfigStrings::STYLESHEETS -#define CONFIG_SYNTAXHIGHLIGHTING ConfigStrings::SYNTAXHIGHLIGHTING -#define CONFIG_TEMPLATEDIR ConfigStrings::TEMPLATEDIR -#define CONFIG_TABSIZE ConfigStrings::TABSIZE -#define CONFIG_TAGFILE ConfigStrings::TAGFILE -#define CONFIG_TRANSLATORS ConfigStrings::TRANSLATORS -#define CONFIG_URL ConfigStrings::URL -#define CONFIG_VERSION ConfigStrings::VERSION -#define CONFIG_VERSIONSYM ConfigStrings::VERSIONSYM -#define CONFIG_FILEEXTENSIONS ConfigStrings::FILEEXTENSIONS -#define CONFIG_IMAGEEXTENSIONS ConfigStrings::IMAGEEXTENSIONS -#define CONFIG_QMLONLY ConfigStrings::QMLONLY -#define CONFIG_QMLTYPESPAGE ConfigStrings::QMLTYPESPAGE -#define CONFIG_WRITEQAPAGES ConfigStrings::WRITEQAPAGES - -QT_END_NAMESPACE - -#endif diff --git a/src/tools/qdoc/cppcodemarker.cpp b/src/tools/qdoc/cppcodemarker.cpp deleted file mode 100644 index 01ff827d58..0000000000 --- a/src/tools/qdoc/cppcodemarker.cpp +++ /dev/null @@ -1,1326 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/* - cppcodemarker.cpp -*/ - -#include "atom.h" -#include "cppcodemarker.h" -#include "node.h" -#include "text.h" -#include "tree.h" -#include <qdebug.h> -#include <ctype.h> - -QT_BEGIN_NAMESPACE - -/*! - The constructor does nothing. - */ -CppCodeMarker::CppCodeMarker() -{ - // nothing. -} - -/*! - The destructor does nothing. - */ -CppCodeMarker::~CppCodeMarker() -{ - // nothing. -} - -/*! - Returns \c true. - */ -bool CppCodeMarker::recognizeCode(const QString & /* code */) -{ - return true; -} - -/*! - Returns \c true if \a ext is any of a list of file extensions - for the C++ language. - */ -bool CppCodeMarker::recognizeExtension(const QString& extension) -{ - QByteArray ext = extension.toLatin1(); - return ext == "c" || - ext == "c++" || - ext == "qdoc" || - ext == "qtt" || - ext == "qtx" || - ext == "cc" || - ext == "cpp" || - ext == "cxx" || - ext == "ch" || - ext == "h" || - ext == "h++" || - ext == "hh" || - ext == "hpp" || - ext == "hxx"; -} - -/*! - Returns \c true if \a lang is either "C" or "Cpp". - */ -bool CppCodeMarker::recognizeLanguage(const QString &lang) -{ - return lang == QLatin1String("C") || lang == QLatin1String("Cpp"); -} - -/*! - Returns the type of atom used to represent C++ code in the documentation. -*/ -Atom::AtomType CppCodeMarker::atomType() const -{ - return Atom::Code; -} - -QString CppCodeMarker::markedUpCode(const QString &code, - const Node *relative, - const Location &location) -{ - return addMarkUp(code, relative, location); -} - -QString CppCodeMarker::markedUpSynopsis(const Node *node, - const Node * /* relative */, - SynopsisStyle style) -{ - const int MaxEnumValues = 6; - const FunctionNode *func; - const PropertyNode *property; - const VariableNode *variable; - const EnumNode *enume; - const TypedefNode *typedeff; - QString synopsis; - QString extra; - QString name; - - name = taggedNode(node); - if (style != Detailed) - name = linkTag(node, name); - name = "<@name>" + name + "</@name>"; - - if ((style == Detailed) && !node->parent()->name().isEmpty() && - (node->type() != Node::Property) && !node->isQmlNode() && !node->isJsNode()) - name.prepend(taggedNode(node->parent()) + "::"); - - switch (node->type()) { - case Node::Namespace: - synopsis = "namespace " + name; - break; - case Node::Class: - synopsis = "class " + name; - break; - case Node::Function: - case Node::QmlSignal: - case Node::QmlSignalHandler: - case Node::QmlMethod: - func = (const FunctionNode *) node; - - if (style != Subpage && !func->returnType().isEmpty()) - synopsis = typified(func->returnType(), true); - synopsis += name; - if (func->metaness() != FunctionNode::MacroWithoutParams) { - synopsis += QLatin1Char('('); - if (!func->parameters().isEmpty()) { - QVector<Parameter>::ConstIterator p = func->parameters().constBegin(); - while (p != func->parameters().constEnd()) { - if (p != func->parameters().constBegin()) - synopsis += ", "; - synopsis += typified((*p).dataType(), true); - if (style != Subpage && !(*p).name().isEmpty()) - synopsis += - "<@param>" + protect((*p).name()) + "</@param>"; - synopsis += protect((*p).rightType()); - if (style != Subpage && !(*p).defaultValue().isEmpty()) - synopsis += " = " + protect((*p).defaultValue()); - ++p; - } - } - synopsis += QLatin1Char(')'); - } - if (func->isConst()) - synopsis += " const"; - - if (style == Summary || style == Accessors) { - if (func->virtualness() != FunctionNode::NonVirtual) - synopsis.prepend("virtual "); - if (func->virtualness() == FunctionNode::PureVirtual) - synopsis.append(" = 0"); - } - else if (style == Subpage) { - if (!func->returnType().isEmpty() && func->returnType() != "void") - synopsis += " : " + typified(func->returnType()); - } - else { - QStringList bracketed; - if (func->isStatic()) { - bracketed += "static"; - } - else if (func->virtualness() != FunctionNode::NonVirtual) { - if (func->virtualness() == FunctionNode::PureVirtual) - bracketed += "pure"; - bracketed += "virtual"; - } - - if (func->access() == Node::Protected) { - bracketed += "protected"; - } - else if (func->access() == Node::Private) { - bracketed += "private"; - } - - if (func->metaness() == FunctionNode::Signal) { - bracketed += "signal"; - } - else if (func->metaness() == FunctionNode::Slot) { - bracketed += "slot"; - } - if (!bracketed.isEmpty()) - extra += QLatin1Char('[') + bracketed.join(' ') + QStringLiteral("] "); - } - break; - case Node::Enum: - enume = static_cast<const EnumNode *>(node); - synopsis = "enum " + name; - if (style == Summary) { - synopsis += " { "; - - QStringList documentedItems = enume->doc().enumItemNames(); - if (documentedItems.isEmpty()) { - foreach (const EnumItem &item, enume->items()) - documentedItems << item.name(); - } - QStringList omitItems = enume->doc().omitEnumItemNames(); - foreach (const QString &item, omitItems) - documentedItems.removeAll(item); - - if (documentedItems.size() <= MaxEnumValues) { - for (int i = 0; i < documentedItems.size(); ++i) { - if (i != 0) - synopsis += ", "; - synopsis += documentedItems.at(i); - } - } - else { - for (int i = 0; i < documentedItems.size(); ++i) { - if (i < MaxEnumValues-2 || i == documentedItems.size()-1) { - if (i != 0) - synopsis += ", "; - synopsis += documentedItems.at(i); - } - else if (i == MaxEnumValues - 1) { - synopsis += ", ..."; - } - } - } - if (!documentedItems.isEmpty()) - synopsis += QLatin1Char(' '); - synopsis += QLatin1Char('}'); - } - break; - case Node::Typedef: - typedeff = static_cast<const TypedefNode *>(node); - if (typedeff->associatedEnum()) { - synopsis = "flags " + name; - } - else { - synopsis = "typedef " + name; - } - break; - case Node::Property: - property = static_cast<const PropertyNode *>(node); - synopsis = name + " : " + typified(property->qualifiedDataType()); - break; - case Node::Variable: - variable = static_cast<const VariableNode *>(node); - if (style == Subpage) { - synopsis = name + " : " + typified(variable->dataType()); - } - else { - synopsis = typified(variable->leftType(), true) + - name + protect(variable->rightType()); - } - break; - default: - synopsis = name; - } - - if (style == Summary) { - if (node->status() == Node::Preliminary) { - extra += "(preliminary) "; - } - else if (node->status() == Node::Deprecated) { - extra += "(deprecated) "; - } - else if (node->status() == Node::Obsolete) { - extra += "(obsolete) "; - } - } - - if (!extra.isEmpty()) { - extra.prepend("<@extra>"); - extra.append("</@extra>"); - } - return extra + synopsis; -} - -/*! - */ -QString CppCodeMarker::markedUpQmlItem(const Node* node, bool summary) -{ - QString name = taggedQmlNode(node); - if (summary) - name = linkTag(node,name); - else if (node->isQmlProperty() || node->isJsProperty()) { - const QmlPropertyNode* pn = static_cast<const QmlPropertyNode*>(node); - if (pn->isAttached()) - name.prepend(pn->element() + QLatin1Char('.')); - } - name = "<@name>" + name + "</@name>"; - QString synopsis; - if (node->isQmlProperty() || node->isJsProperty()) { - const QmlPropertyNode* pn = static_cast<const QmlPropertyNode*>(node); - synopsis = name + " : " + typified(pn->dataType()); - } - else if ((node->type() == Node::QmlMethod) || - (node->type() == Node::QmlSignal) || - (node->type() == Node::QmlSignalHandler)) { - const FunctionNode* func = static_cast<const FunctionNode*>(node); - if (!func->returnType().isEmpty()) - synopsis = typified(func->returnType(), true) + name; - else - synopsis = name; - synopsis += QLatin1Char('('); - if (!func->parameters().isEmpty()) { - QVector<Parameter>::ConstIterator p = func->parameters().constBegin(); - while (p != func->parameters().constEnd()) { - if (p != func->parameters().constBegin()) - synopsis += ", "; - synopsis += typified((*p).dataType(), true); - if (!(*p).name().isEmpty()) - synopsis += "<@param>" + protect((*p).name()) + "</@param>"; - synopsis += protect((*p).rightType()); - ++p; - } - } - synopsis += QLatin1Char(')'); - } - else - synopsis = name; - - QString extra; - if (summary) { - if (node->status() == Node::Preliminary) { - extra += " (preliminary)"; - } - else if (node->status() == Node::Deprecated) { - extra += " (deprecated)"; - } - else if (node->status() == Node::Obsolete) { - extra += " (obsolete)"; - } - } - - if (!extra.isEmpty()) { - extra.prepend("<@extra>"); - extra.append("</@extra>"); - } - return synopsis + extra; -} - -QString CppCodeMarker::markedUpName(const Node *node) -{ - QString name = linkTag(node, taggedNode(node)); - if (node->type() == Node::Function) - name += "()"; - return name; -} - -QString CppCodeMarker::markedUpFullName(const Node *node, const Node *relative) -{ - if (node->name().isEmpty()) { - return "global"; - } - else { - QString fullName; - for (;;) { - fullName.prepend(markedUpName(node)); - if (node->parent() == relative || node->parent()->name().isEmpty()) - break; - fullName.prepend("<@op>::</@op>"); - node = node->parent(); - } - return fullName; - } -} - -QString CppCodeMarker::markedUpEnumValue(const QString &enumValue, const Node *relative) -{ - if (relative->type() != Node::Enum) - return enumValue; - - const Node *node = relative->parent(); - QString fullName; - while (node->parent()) { - fullName.prepend(markedUpName(node)); - if (node->parent() == relative || node->parent()->name().isEmpty()) - break; - fullName.prepend("<@op>::</@op>"); - node = node->parent(); - } - if (!fullName.isEmpty()) - fullName.append("<@op>::</@op>"); - fullName.append(enumValue); - return fullName; -} - -QString CppCodeMarker::markedUpIncludes(const QStringList& includes) -{ - QString code; - - QStringList::ConstIterator inc = includes.constBegin(); - while (inc != includes.constEnd()) { - code += "<@preprocessor>#include <<@headerfile>" + *inc + "</@headerfile>></@preprocessor>\n"; - ++inc; - } - return code; -} - -QString CppCodeMarker::functionBeginRegExp(const QString& funcName) -{ - return QLatin1Char('^') + QRegExp::escape(funcName) + QLatin1Char('$'); - -} - -QString CppCodeMarker::functionEndRegExp(const QString& /* funcName */) -{ - return "^\\}$"; -} - -QList<Section> CppCodeMarker::sections(const Aggregate *inner, - SynopsisStyle style, - Status status) -{ - QList<Section> sections; - - if (inner->isClass()) { - if (style == Summary) { - FastSection privateFunctions(inner, - "Private Functions", - QString(), - "private function", - "private functions"); - FastSection privateSlots(inner, "Private Slots", QString(), "private slot", "private slots"); - FastSection privateTypes(inner, "Private Types", QString(), "private type", "private types"); - FastSection protectedFunctions(inner, - "Protected Functions", - QString(), - "protected function", - "protected functions"); - FastSection protectedSlots(inner, - "Protected Slots", - QString(), - "protected slot", - "protected slots"); - FastSection protectedTypes(inner, - "Protected Types", - QString(), - "protected type", - "protected types"); - FastSection protectedVariables(inner, - "Protected Variables", - QString(), - "protected type", - "protected variables"); - FastSection publicFunctions(inner, - "Public Functions", - QString(), - "public function", - "public functions"); - FastSection publicSignals(inner, "Signals", QString(), "signal", "signals"); - FastSection publicSlots(inner, "Public Slots", QString(), "public slot", "public slots"); - FastSection publicTypes(inner, "Public Types", QString(), "public type", "public types"); - FastSection publicVariables(inner, - "Public Variables", - QString(), - "public variable", - "public variables"); - FastSection properties(inner, "Properties", QString(), "property", "properties"); - FastSection relatedNonMembers(inner, - "Related Non-Members", - QString(), - "related non-member", - "related non-members"); - FastSection staticPrivateMembers(inner, - "Static Private Members", - QString(), - "static private member", - "static private members"); - FastSection staticProtectedMembers(inner, - "Static Protected Members", - QString(), - "static protected member", - "static protected members"); - FastSection staticPublicMembers(inner, - "Static Public Members", - QString(), - "static public member", - "static public members"); - FastSection macros(inner, "Macros", QString(), "macro", "macros"); - - NodeList::ConstIterator r = inner->relatedNodes().constBegin(); - while (r != inner->relatedNodes().constEnd()) { - if ((*r)->type() == Node::Function) { - FunctionNode *func = static_cast<FunctionNode *>(*r); - if (func->isMacro()) - insert(macros, *r, style, status); - else - insert(relatedNonMembers, *r, style, status); - } - else { - insert(relatedNonMembers, *r, style, status); - } - ++r; - } - - QStack<const Aggregate *> stack; - stack.push(inner); - while (!stack.isEmpty()) { - const Aggregate* ancestor = stack.pop(); - - NodeList::ConstIterator c = ancestor->childNodes().constBegin(); - while (c != ancestor->childNodes().constEnd()) { - bool isSlot = false; - bool isSignal = false; - bool isStatic = false; - if ((*c)->type() == Node::Function) { - const FunctionNode *func = (const FunctionNode *) *c; - isSlot = (func->metaness() == FunctionNode::Slot); - isSignal = (func->metaness() == FunctionNode::Signal); - isStatic = func->isStatic(); - if (func->hasAssociatedProperties() && !func->hasActiveAssociatedProperty()) { - ++c; - continue; - } - } - else if ((*c)->type() == Node::Variable) { - const VariableNode *var = static_cast<const VariableNode *>(*c); - isStatic = var->isStatic(); - } - - switch ((*c)->access()) { - case Node::Public: - if (isSlot) { - insert(publicSlots, *c, style, status); - } - else if (isSignal) { - insert(publicSignals, *c, style, status); - } - else if (isStatic) { - if ((*c)->type() != Node::Variable || !(*c)->doc().isEmpty()) - insert(staticPublicMembers,*c,style,status); - } - else if ((*c)->type() == Node::Property) { - insert(properties, *c, style, status); - } - else if ((*c)->type() == Node::Variable) { - if (!(*c)->doc().isEmpty()) - insert(publicVariables, *c, style, status); - } - else if ((*c)->type() == Node::Function) { - if (!insertReimpFunc(publicFunctions,*c,status)) { - insert(publicFunctions, *c, style, status); - } - } - else { - insert(publicTypes, *c, style, status); - } - break; - case Node::Protected: - if (isSlot) { - insert(protectedSlots, *c, style, status); - } - else if (isStatic) { - if ((*c)->type() != Node::Variable || !(*c)->doc().isEmpty()) - insert(staticProtectedMembers,*c,style,status); - } - else if ((*c)->type() == Node::Variable) { - if (!(*c)->doc().isEmpty()) - insert(protectedVariables,*c,style,status); - } - else if ((*c)->type() == Node::Function) { - if (!insertReimpFunc(protectedFunctions,*c,status)) { - insert(protectedFunctions, *c, style, status); - } - } - else { - insert(protectedTypes, *c, style, status); - } - break; - case Node::Private: - if (isSlot) { - insert(privateSlots, *c, style, status); - } - else if (isStatic) { - if ((*c)->type() != Node::Variable || !(*c)->doc().isEmpty()) - insert(staticPrivateMembers,*c,style,status); - } - else if ((*c)->type() == Node::Function) { - if (!insertReimpFunc(privateFunctions,*c,status)) { - insert(privateFunctions, *c, style, status); - } - } - else { - insert(privateTypes,*c,style,status); - } - } - ++c; - } - - if (ancestor->isClass()) { - const ClassNode* cn = static_cast<const ClassNode*>(ancestor); - QList<RelatedClass>::ConstIterator r = cn->baseClasses().constBegin(); - while (r != cn->baseClasses().constEnd()) { - if ((*r).node_) - stack.prepend((*r).node_); - ++r; - } - } - } - append(sections, publicTypes); - append(sections, properties); - append(sections, publicFunctions); - append(sections, publicSlots); - append(sections, publicSignals); - append(sections, publicVariables); - append(sections, staticPublicMembers); - append(sections, protectedTypes); - append(sections, protectedFunctions); - append(sections, protectedSlots); - append(sections, protectedVariables); - append(sections, staticProtectedMembers); - append(sections, privateTypes); - append(sections, privateFunctions); - append(sections, privateSlots); - append(sections, staticPrivateMembers); - append(sections, relatedNonMembers); - append(sections, macros); - } - else if (style == Detailed) { - FastSection memberFunctions(inner,"Member Function Documentation","func","member","members"); - FastSection memberTypes(inner,"Member Type Documentation","types","member","members"); - FastSection memberVariables(inner,"Member Variable Documentation","vars","member","members"); - FastSection properties(inner,"Property Documentation","prop","member","members"); - FastSection relatedNonMembers(inner,"Related Non-Members","relnonmem","member","members"); - FastSection macros(inner,"Macro Documentation","macros","member","members"); - - NodeList::ConstIterator r = inner->relatedNodes().constBegin(); - while (r != inner->relatedNodes().constEnd()) { - if ((*r)->type() == Node::Function) { - FunctionNode *func = static_cast<FunctionNode *>(*r); - if (func->isMacro()) - insert(macros, *r, style, status); - else - insert(relatedNonMembers, *r, style, status); - } - else { - insert(relatedNonMembers, *r, style, status); - } - ++r; - } - - NodeList::ConstIterator c = inner->childNodes().constBegin(); - while (c != inner->childNodes().constEnd()) { - if ((*c)->type() == Node::Enum || - (*c)->type() == Node::Typedef) { - insert(memberTypes, *c, style, status); - } - else if ((*c)->type() == Node::Property) { - insert(properties, *c, style, status); - } - else if ((*c)->type() == Node::Variable) { - if (!(*c)->doc().isEmpty()) - insert(memberVariables, *c, style, status); - } - else if ((*c)->type() == Node::Function) { - FunctionNode *function = static_cast<FunctionNode *>(*c); - if (!function->hasAssociatedProperties() || !function->doc().isEmpty()) - insert(memberFunctions, function, style, status); - } - ++c; - } - - append(sections, memberTypes); - append(sections, properties); - append(sections, memberFunctions); - append(sections, memberVariables); - append(sections, relatedNonMembers); - append(sections, macros); - } - else { - FastSection all(inner,QString(),QString(),"member","members"); - - QStack<const Aggregate*> stack; - stack.push(inner); - - while (!stack.isEmpty()) { - const Aggregate* ancestor = stack.pop(); - NodeList::ConstIterator c = ancestor->childNodes().constBegin(); - while (c != ancestor->childNodes().constEnd()) { - if ((*c)->access() != Node::Private && (*c)->type() != Node::Property) - insert(all, *c, style, status); - ++c; - } - - if (ancestor->isClass()) { - const ClassNode* cn = static_cast<const ClassNode*>(ancestor); - QList<RelatedClass>::ConstIterator r = cn->baseClasses().constBegin(); - while (r != cn->baseClasses().constEnd()) { - if ((*r).node_) - stack.prepend((*r).node_); - ++r; - } - } - } - append(sections, all); - } - } - else { - if (style == Summary || style == Detailed) { - FastSection namespaces(inner, - "Namespaces", - style == Detailed ? "nmspace" : QString(), - "namespace", - "namespaces"); - FastSection classes(inner, - "Classes", - style == Detailed ? "classes" : QString(), - "class", - "classes"); - FastSection types(inner, - style == Summary ? "Types" : "Type Documentation", - style == Detailed ? "types" : QString(), - "type", - "types"); - FastSection variables(inner, - style == Summary ? "Variables" : "Variable Documentation", - style == Detailed ? "vars" : QString(), - "variable", - "variables"); - FastSection staticVariables(inner, - "Static Variables", - QString(), - "static variable", - "static variables"); - FastSection functions(inner, - style == Summary ? - "Functions" : "Function Documentation", - style == Detailed ? "func" : QString(), - "function", - "functions"); - FastSection macros(inner, - style == Summary ? - "Macros" : "Macro Documentation", - style == Detailed ? "macros" : QString(), - "macro", - "macros"); - - NodeList nodeList = inner->childNodes(); - nodeList += inner->relatedNodes(); - - NodeList::ConstIterator n = nodeList.constBegin(); - while (n != nodeList.constEnd()) { - switch ((*n)->type()) { - case Node::Namespace: - insert(namespaces, *n, style, status); - break; - case Node::Class: - insert(classes, *n, style, status); - break; - case Node::Enum: - case Node::Typedef: - insert(types, *n, style, status); - break; - case Node::Function: - { - FunctionNode *func = static_cast<FunctionNode *>(*n); - if (func->isMacro()) - insert(macros, *n, style, status); - else - insert(functions, *n, style, status); - } - break; - case Node::Variable: - { - const VariableNode* var = static_cast<const VariableNode*>(*n); - if (!var->doc().isEmpty()) { - if (var->isStatic()) - insert(staticVariables,*n,style,status); - else - insert(variables, *n, style, status); - } - } - break; - default: - break; - } - ++n; - } - if (inner->isNamespace()) { - const NamespaceNode* ns = static_cast<const NamespaceNode*>(inner); - if (!ns->orphans().isEmpty()) { - foreach (Node* n, ns->orphans()) { - // Use inner as a temporary parent when inserting orphans - Aggregate* p = n->parent(); - n->setParent(const_cast<Aggregate*>(inner)); - if (n->isClass()) - insert(classes, n, style, status); - else if (n->isNamespace()) - insert(namespaces, n, style, status); - n->setParent(p); - } - } - } - append(sections, namespaces); - append(sections, classes); - append(sections, types); - append(sections, variables); - append(sections, staticVariables); - append(sections, functions); - append(sections, macros); - } - } - - return sections; -} - -/* - @char - @class - @comment - @function - @keyword - @number - @op - @preprocessor - @string - @type -*/ - -QString CppCodeMarker::addMarkUp(const QString &in, - const Node * /* relative */, - const Location & /* location */) -{ - static QSet<QString> types; - static QSet<QString> keywords; - - if (types.isEmpty()) { - // initialize statics - Q_ASSERT(keywords.isEmpty()); - static const QString typeTable[] = { - QLatin1String("bool"), QLatin1String("char"), QLatin1String("double"), QLatin1String("float"), QLatin1String("int"), QLatin1String("long"), QLatin1String("short"), - QLatin1String("signed"), QLatin1String("unsigned"), QLatin1String("uint"), QLatin1String("ulong"), QLatin1String("ushort"), QLatin1String("uchar"), QLatin1String("void"), - QLatin1String("qlonglong"), QLatin1String("qulonglong"), - QLatin1String("qint"), QLatin1String("qint8"), QLatin1String("qint16"), QLatin1String("qint32"), QLatin1String("qint64"), - QLatin1String("quint"), QLatin1String("quint8"), QLatin1String("quint16"), QLatin1String("quint32"), QLatin1String("quint64"), - QLatin1String("qreal"), QLatin1String("cond") - }; - - static const QString keywordTable[] = { - QLatin1String("and"), QLatin1String("and_eq"), QLatin1String("asm"), QLatin1String("auto"), QLatin1String("bitand"), QLatin1String("bitor"), QLatin1String("break"), - QLatin1String("case"), QLatin1String("catch"), QLatin1String("class"), QLatin1String("compl"), QLatin1String("const"), QLatin1String("const_cast"), - QLatin1String("continue"), QLatin1String("default"), QLatin1String("delete"), QLatin1String("do"), QLatin1String("dynamic_cast"), QLatin1String("else"), - QLatin1String("enum"), QLatin1String("explicit"), QLatin1String("export"), QLatin1String("extern"), QLatin1String("false"), QLatin1String("for"), QLatin1String("friend"), - QLatin1String("goto"), QLatin1String("if"), QLatin1String("include"), QLatin1String("inline"), QLatin1String("monitor"), QLatin1String("mutable"), QLatin1String("namespace"), - QLatin1String("new"), QLatin1String("not"), QLatin1String("not_eq"), QLatin1String("operator"), QLatin1String("or"), QLatin1String("or_eq"), QLatin1String("private"), QLatin1String("protected"), - QLatin1String("public"), QLatin1String("register"), QLatin1String("reinterpret_cast"), QLatin1String("return"), QLatin1String("sizeof"), - QLatin1String("static"), QLatin1String("static_cast"), QLatin1String("struct"), QLatin1String("switch"), QLatin1String("template"), QLatin1String("this"), - QLatin1String("throw"), QLatin1String("true"), QLatin1String("try"), QLatin1String("typedef"), QLatin1String("typeid"), QLatin1String("typename"), QLatin1String("union"), - QLatin1String("using"), QLatin1String("virtual"), QLatin1String("volatile"), QLatin1String("wchar_t"), QLatin1String("while"), QLatin1String("xor"), - QLatin1String("xor_eq"), QLatin1String("synchronized"), - // Qt specific - QLatin1String("signals"), QLatin1String("slots"), QLatin1String("emit") - }; - - types.reserve(sizeof(typeTable) / sizeof(QString)); - for (int j = sizeof(typeTable) / sizeof(QString) - 1; j; --j) - types.insert(typeTable[j]); - - keywords.reserve(sizeof(keywordTable) / sizeof(QString)); - for (int j = sizeof(keywordTable) / sizeof(QString) - 1; j; --j) - keywords.insert(keywordTable[j]); - } -#define readChar() \ - ch = (i < (int)code.length()) ? code[i++].cell() : EOF - - QString code = in; - QString out; - QStringRef text; - int braceDepth = 0; - int parenDepth = 0; - int i = 0; - int start = 0; - int finish = 0; - QChar ch; - QRegExp classRegExp("Qt?(?:[A-Z3]+[a-z][A-Za-z]*|t)"); - QRegExp functionRegExp("q([A-Z][a-z]+)+"); - QRegExp findFunctionRegExp(QStringLiteral("^\\s*\\(")); - - readChar(); - - while (ch != EOF) { - QString tag; - bool target = false; - - if (ch.isLetter() || ch == '_') { - QString ident; - do { - ident += ch; - finish = i; - readChar(); - } while (ch.isLetterOrNumber() || ch == '_'); - - if (classRegExp.exactMatch(ident)) { - tag = QStringLiteral("type"); - } else if (functionRegExp.exactMatch(ident)) { - tag = QStringLiteral("func"); - target = true; - } else if (types.contains(ident)) { - tag = QStringLiteral("type"); - } else if (keywords.contains(ident)) { - tag = QStringLiteral("keyword"); - } else if (braceDepth == 0 && parenDepth == 0) { - if (code.indexOf(findFunctionRegExp, i - 1) == i - 1) - tag = QStringLiteral("func"); - target = true; - } - } else if (ch.isDigit()) { - do { - finish = i; - readChar(); - } while (ch.isLetterOrNumber() || ch == '.'); - tag = QStringLiteral("number"); - } else { - switch (ch.unicode()) { - case '+': - case '-': - case '!': - case '%': - case '^': - case '&': - case '*': - case ',': - case '.': - case '<': - case '=': - case '>': - case '?': - case '[': - case ']': - case '|': - case '~': - finish = i; - readChar(); - tag = QStringLiteral("op"); - break; - case '"': - finish = i; - readChar(); - - while (ch != EOF && ch != '"') { - if (ch == '\\') - readChar(); - readChar(); - } - finish = i; - readChar(); - tag = QStringLiteral("string"); - break; - case '#': - finish = i; - readChar(); - while (ch != EOF && ch != '\n') { - if (ch == '\\') - readChar(); - finish = i; - readChar(); - } - tag = QStringLiteral("preprocessor"); - break; - case '\'': - finish = i; - readChar(); - - while (ch != EOF && ch != '\'') { - if (ch == '\\') - readChar(); - readChar(); - } - finish = i; - readChar(); - tag = QStringLiteral("char"); - break; - case '(': - finish = i; - readChar(); - parenDepth++; - break; - case ')': - finish = i; - readChar(); - parenDepth--; - break; - case ':': - finish = i; - readChar(); - if (ch == ':') { - finish = i; - readChar(); - tag = QStringLiteral("op"); - } - break; - case '/': - finish = i; - readChar(); - if (ch == '/') { - do { - finish = i; - readChar(); - } while (ch != EOF && ch != '\n'); - tag = QStringLiteral("comment"); - } else if (ch == '*') { - bool metAster = false; - bool metAsterSlash = false; - - finish = i; - readChar(); - - while (!metAsterSlash) { - if (ch == EOF) - break; - - if (ch == '*') - metAster = true; - else if (metAster && ch == '/') - metAsterSlash = true; - else - metAster = false; - finish = i; - readChar(); - } - tag = QStringLiteral("comment"); - } else { - tag = QStringLiteral("op"); - } - break; - case '{': - finish = i; - readChar(); - braceDepth++; - break; - case '}': - finish = i; - readChar(); - braceDepth--; - break; - default: - finish = i; - readChar(); - } - } - - text = code.midRef(start, finish - start); - start = finish; - - if (!tag.isEmpty()) { - out += QStringLiteral("<@"); - out += tag; - if (target) { - out += QStringLiteral(" target=\""); - out += text; - out += QStringLiteral("()\""); - } - out += QStringLiteral(">"); - } - - appendProtectedString(&out, text); - - if (!tag.isEmpty()) { - out += QStringLiteral("</@"); - out += tag; - out += QStringLiteral(">"); - } - } - - if (start < code.length()) { - appendProtectedString(&out, code.midRef(start)); - } - - return out; -} - -/*! - This function is for documenting QML properties. It returns - the list of documentation sections for the children of the - \a qmlTypeNode. - */ -QList<Section> CppCodeMarker::qmlSections(QmlTypeNode* qmlTypeNode, SynopsisStyle style, Status status) -{ - QList<Section> sections; - if (qmlTypeNode) { - if (style == Summary) { - FastSection qmlproperties(qmlTypeNode, - "Properties", - QString(), - "property", - "properties"); - FastSection qmlattachedproperties(qmlTypeNode, - "Attached Properties", - QString(), - "property", - "properties"); - FastSection qmlsignals(qmlTypeNode, - "Signals", - QString(), - "signal", - "signals"); - FastSection qmlsignalhandlers(qmlTypeNode, - "Signal Handlers", - QString(), - "signal handler", - "signal handlers"); - FastSection qmlattachedsignals(qmlTypeNode, - "Attached Signals", - QString(), - "signal", - "signals"); - FastSection qmlmethods(qmlTypeNode, - "Methods", - QString(), - "method", - "methods"); - FastSection qmlattachedmethods(qmlTypeNode, - "Attached Methods", - QString(), - "method", - "methods"); - - QmlTypeNode* qcn = qmlTypeNode; - while (qcn != 0) { - NodeList::ConstIterator c = qcn->childNodes().constBegin(); - while (c != qcn->childNodes().constEnd()) { - if ((*c)->status() == Node::Internal) { - ++c; - continue; - } - if ((*c)->isQmlPropertyGroup() || (*c)->isJsPropertyGroup()) { - insert(qmlproperties, *c, style, status); - } - else if ((*c)->isQmlProperty() || (*c)->isJsProperty()) { - const QmlPropertyNode* pn = static_cast<const QmlPropertyNode*>(*c); - if (pn->isAttached()) - insert(qmlattachedproperties,*c,style, status); - else { - insert(qmlproperties,*c,style, status); - } - } - else if ((*c)->isQmlSignal() || (*c)->isJsSignal()) { - const FunctionNode* sn = static_cast<const FunctionNode*>(*c); - if (sn->isAttached()) - insert(qmlattachedsignals,*c,style, status); - else - insert(qmlsignals,*c,style, status); - } - else if ((*c)->isQmlSignalHandler() || (*c)->isJsSignalHandler()) { - insert(qmlsignalhandlers,*c,style, status); - } - else if ((*c)->isQmlMethod() || (*c)->isJsMethod()) { - const FunctionNode* mn = static_cast<const FunctionNode*>(*c); - if (mn->isAttached()) - insert(qmlattachedmethods,*c,style, status); - else - insert(qmlmethods,*c,style, status); - } - ++c; - } - if (qcn->qmlBaseNode() != 0) { - qcn = static_cast<QmlTypeNode*>(qcn->qmlBaseNode()); - if (!qcn->isAbstract()) - qcn = 0; - } - else - qcn = 0; - } - append(sections,qmlproperties); - append(sections,qmlattachedproperties); - append(sections,qmlsignals); - append(sections,qmlsignalhandlers); - append(sections,qmlattachedsignals); - append(sections,qmlmethods); - append(sections,qmlattachedmethods); - } - else if (style == Detailed) { - FastSection qmlproperties(qmlTypeNode, "Property Documentation","qmlprop","member","members"); - FastSection qmlattachedproperties(qmlTypeNode,"Attached Property Documentation","qmlattprop", - "member","members"); - FastSection qmlsignals(qmlTypeNode,"Signal Documentation","qmlsig","signal","signals"); - FastSection qmlsignalhandlers(qmlTypeNode,"Signal Handler Documentation","qmlsighan","signal handler","signal handlers"); - FastSection qmlattachedsignals(qmlTypeNode,"Attached Signal Documentation","qmlattsig", - "signal","signals"); - FastSection qmlmethods(qmlTypeNode,"Method Documentation","qmlmeth","member","members"); - FastSection qmlattachedmethods(qmlTypeNode,"Attached Method Documentation","qmlattmeth", - "member","members"); - QmlTypeNode* qcn = qmlTypeNode; - while (qcn != 0) { - NodeList::ConstIterator c = qcn->childNodes().constBegin(); - while (c != qcn->childNodes().constEnd()) { - if ((*c)->status() == Node::Internal) { - ++c; - continue; - } - if ((*c)->isQmlPropertyGroup() || (*c)->isJsPropertyGroup()) { - insert(qmlproperties,*c,style, status); - } - else if ((*c)->isQmlProperty() || (*c)->isJsProperty()) { - const QmlPropertyNode* pn = static_cast<const QmlPropertyNode*>(*c); - if (pn->isAttached()) - insert(qmlattachedproperties,*c,style, status); - else - insert(qmlproperties,*c,style, status); - } - else if ((*c)->isQmlSignal() || (*c)->isJsSignal()) { - const FunctionNode* sn = static_cast<const FunctionNode*>(*c); - if (sn->isAttached()) - insert(qmlattachedsignals,*c,style, status); - else - insert(qmlsignals,*c,style, status); - } - else if ((*c)->isQmlSignalHandler() || (*c)->isJsSignalHandler()) { - insert(qmlsignalhandlers,*c,style, status); - } - else if ((*c)->isQmlMethod() || (*c)->isJsMethod()) { - const FunctionNode* mn = static_cast<const FunctionNode*>(*c); - if (mn->isAttached()) - insert(qmlattachedmethods,*c,style, status); - else - insert(qmlmethods,*c,style, status); - } - ++c; - } - if (qcn->qmlBaseNode() != 0) { - qcn = static_cast<QmlTypeNode*>(qcn->qmlBaseNode()); - if (!qcn->isAbstract()) - qcn = 0; - } - else - qcn = 0; - } - append(sections,qmlproperties); - append(sections,qmlattachedproperties); - append(sections,qmlsignals); - append(sections,qmlsignalhandlers); - append(sections,qmlattachedsignals); - append(sections,qmlmethods); - append(sections,qmlattachedmethods); - } - else { - /* - This is where the list of all members including inherited - members is prepared. - */ - ClassMap* classMap = 0; - FastSection all(qmlTypeNode,QString(),QString(),"member","members"); - QmlTypeNode* current = qmlTypeNode; - while (current != 0) { - /* - If the QML type is abstract, do not create - a new entry in the list for it. Instead, - add its members to the current entry. - - However, if the first class is abstract, - there is no current entry. In that case, - create a new entry in the list anyway. - I'm not sure that is correct, but it at - least can prevent a crash. - */ - if (!current->isAbstract() || !classMap) { - classMap = new ClassMap; - classMap->first = current; - all.classMapList_.append(classMap); - } - NodeList::ConstIterator c = current->childNodes().constBegin(); - while (c != current->childNodes().constEnd()) { - if ((*c)->isQmlPropertyGroup() || (*c)->isJsPropertyGroup()) { - const QmlPropertyGroupNode* qpgn = static_cast<const QmlPropertyGroupNode*>(*c); - NodeList::ConstIterator p = qpgn->childNodes().constBegin(); - while (p != qpgn->childNodes().constEnd()) { - if ((*p)->isQmlProperty() || (*c)->isJsProperty()) { - QString key = (*p)->name(); - key = sortName(*p, &key); - all.memberMap.insert(key,*p); - classMap->second.insert(key,*p); - } - ++p; - } - } - else { - QString key = (*c)->name(); - key = sortName(*c, &key); - all.memberMap.insert(key,*c); - classMap->second.insert(key,*c); - } - ++c; - } - current = current->qmlBaseNode(); - while (current) { - if (current->isAbstract()) - break; - if (current->isInternal()) - current = current->qmlBaseNode(); - else - break; - } - } - append(sections, all, true); - } - } - - return sections; -} - -QT_END_NAMESPACE diff --git a/src/tools/qdoc/cppcodemarker.h b/src/tools/qdoc/cppcodemarker.h deleted file mode 100644 index aa759f2993..0000000000 --- a/src/tools/qdoc/cppcodemarker.h +++ /dev/null @@ -1,85 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/* - cppcodemarker.h -*/ - -#ifndef CPPCODEMARKER_H -#define CPPCODEMARKER_H - -#include "codemarker.h" - -QT_BEGIN_NAMESPACE - -class CppCodeMarker : public CodeMarker -{ - Q_DECLARE_TR_FUNCTIONS(QDoc::CppCodeMarker) - -public: - CppCodeMarker(); - ~CppCodeMarker(); - - virtual bool recognizeCode(const QString& code) Q_DECL_OVERRIDE; - virtual bool recognizeExtension(const QString& ext) Q_DECL_OVERRIDE; - virtual bool recognizeLanguage(const QString& lang) Q_DECL_OVERRIDE; - virtual Atom::AtomType atomType() const Q_DECL_OVERRIDE; - virtual QString markedUpCode(const QString& code, - const Node *relative, - const Location &location) Q_DECL_OVERRIDE; - virtual QString markedUpSynopsis(const Node *node, - const Node *relative, - SynopsisStyle style) Q_DECL_OVERRIDE; - virtual QString markedUpQmlItem(const Node *node, bool summary) Q_DECL_OVERRIDE; - virtual QString markedUpName(const Node *node) Q_DECL_OVERRIDE; - virtual QString markedUpFullName(const Node *node, const Node *relative) Q_DECL_OVERRIDE; - virtual QString markedUpEnumValue(const QString &enumValue, const Node *relative) Q_DECL_OVERRIDE; - virtual QString markedUpIncludes(const QStringList& includes) Q_DECL_OVERRIDE; - virtual QString functionBeginRegExp(const QString& funcName) Q_DECL_OVERRIDE; - virtual QString functionEndRegExp(const QString& funcName) Q_DECL_OVERRIDE; - virtual QList<Section> sections(const Aggregate *innerNode, - SynopsisStyle style, - Status status) Q_DECL_OVERRIDE; - virtual QList<Section> qmlSections(QmlTypeNode* qmlTypeNode, - SynopsisStyle style, - Status status = Okay) Q_DECL_OVERRIDE; - -private: - QString addMarkUp(const QString& protectedCode, - const Node *relative, - const Location &location); -}; - -QT_END_NAMESPACE - -#endif diff --git a/src/tools/qdoc/cppcodeparser.cpp b/src/tools/qdoc/cppcodeparser.cpp deleted file mode 100644 index 0405cc2c2b..0000000000 --- a/src/tools/qdoc/cppcodeparser.cpp +++ /dev/null @@ -1,2611 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/* - cppcodeparser.cpp -*/ - -#include <qfile.h> -#include <stdio.h> -#include <errno.h> -#include "codechunk.h" -#include "config.h" -#include "cppcodeparser.h" -#include "tokenizer.h" -#include "qdocdatabase.h" -#include <qdebug.h> -#include "generator.h" - -QT_BEGIN_NAMESPACE - -/* qmake ignore Q_OBJECT */ - -static bool inMacroCommand_ = false; -static bool parsingHeaderFile_ = false; -QStringList CppCodeParser::exampleFiles; -QStringList CppCodeParser::exampleDirs; -CppCodeParser* CppCodeParser::cppParser_ = 0; - -/*! - The constructor initializes some regular expressions - and calls reset(). - */ -CppCodeParser::CppCodeParser() - : varComment("/\\*\\s*([a-zA-Z_0-9]+)\\s*\\*/"), sep("(?:<[^>]+>)?::") -{ - reset(); - cppParser_ = this; -} - -/*! - The destructor is trivial. - */ -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); - - /* - All these can appear in a C++ namespace. Don't add - anything that can't be in a C++ namespace. - */ - nodeTypeMap.insert(COMMAND_NAMESPACE, Node::Namespace); - nodeTypeMap.insert(COMMAND_CLASS, Node::Class); - nodeTypeMap.insert(COMMAND_ENUM, Node::Enum); - nodeTypeMap.insert(COMMAND_TYPEDEF, Node::Typedef); - nodeTypeMap.insert(COMMAND_PROPERTY, Node::Property); - nodeTypeMap.insert(COMMAND_VARIABLE, Node::Variable); - - exampleFiles = config.getCanonicalPathList(CONFIG_EXAMPLES); - exampleDirs = config.getCanonicalPathList(CONFIG_EXAMPLEDIRS); - QStringList exampleFilePatterns = config.getStringList( - CONFIG_EXAMPLES + Config::dot + CONFIG_FILEEXTENSIONS); - - if (!exampleFilePatterns.isEmpty()) - exampleNameFilter = exampleFilePatterns.join(' '); - else - exampleNameFilter = "*.cpp *.h *.js *.xq *.svg *.xml *.dita *.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. - */ -QStringList CppCodeParser::headerFileNameFilter() -{ - return QStringList() << "*.ch" << "*.h" << "*.h++" << "*.hh" << "*.hpp" << "*.hxx"; -} - -/*! - Returns a list of extensions for source files, i.e. not - header files. - */ -QStringList CppCodeParser::sourceFileNameFilter() -{ - return QStringList() << "*.c++" << "*.cc" << "*.cpp" << "*.cxx" << "*.mm"; -} - -/*! - Parse the C++ header file identified by \a filePath and add - the parsed contents to the database. The \a location is used - for reporting errors. - */ -void CppCodeParser::parseHeaderFile(const Location& location, const QString& filePath) -{ - QFile in(filePath); - currentFile_ = filePath; - if (!in.open(QIODevice::ReadOnly)) { - location.error(tr("Cannot open C++ header file '%1'").arg(filePath)); - currentFile_.clear(); - return; - } - - reset(); - Location fileLocation(filePath); - Tokenizer fileTokenizer(fileLocation, in); - tokenizer = &fileTokenizer; - readToken(); - parsingHeaderFile_ = true; - matchDeclList(qdb_->primaryTreeRoot()); - parsingHeaderFile_ = false; - if (!fileTokenizer.version().isEmpty()) - qdb_->setVersion(fileTokenizer.version()); - in.close(); - - if (fileLocation.fileName() == "qiterator.h") - parseQiteratorDotH(location, filePath); - currentFile_.clear(); -} - -/*! - Get ready to parse the C++ cpp file identified by \a filePath - and add its parsed contents to the database. \a location is - used for reporting errors. - - Call matchDocsAndStuff() to do all the parsing and tree building. - */ -void CppCodeParser::parseSourceFile(const Location& location, const QString& filePath) -{ - QFile in(filePath); - currentFile_ = filePath; - if (!in.open(QIODevice::ReadOnly)) { - location.error(tr("Cannot open C++ source file '%1' (%2)").arg(filePath).arg(strerror(errno))); - currentFile_.clear(); - return; - } - - reset(); - Location fileLocation(filePath); - Tokenizer fileTokenizer(fileLocation, in); - tokenizer = &fileTokenizer; - readToken(); - - /* - The set of open namespaces is cleared before parsing - each source file. The word "source" here means cpp file. - */ - qdb_->clearOpenNamespaces(); - - matchDocsAndStuff(); - in.close(); - currentFile_.clear(); -} - -/*! - This is called after all the C++ header files have been - parsed. The most important thing it does is resolve C++ - class inheritance links in the tree. It also initializes - a bunch of other collections. - */ -void CppCodeParser::doneParsingHeaderFiles() -{ - QMapIterator<QString, QString> i(sequentialIteratorClasses); - while (i.hasNext()) { - i.next(); - instantiateIteratorMacro(i.key(), i.value(), sequentialIteratorDefinition); - } - i = mutableSequentialIteratorClasses; - while (i.hasNext()) { - i.next(); - instantiateIteratorMacro(i.key(), i.value(), mutableSequentialIteratorDefinition); - } - i = associativeIteratorClasses; - while (i.hasNext()) { - i.next(); - instantiateIteratorMacro(i.key(), i.value(), associativeIteratorDefinition); - } - i = mutableAssociativeIteratorClasses; - while (i.hasNext()) { - i.next(); - instantiateIteratorMacro(i.key(), i.value(), mutableAssociativeIteratorDefinition); - } - sequentialIteratorDefinition.clear(); - mutableSequentialIteratorDefinition.clear(); - associativeIteratorDefinition.clear(); - mutableAssociativeIteratorDefinition.clear(); - sequentialIteratorClasses.clear(); - mutableSequentialIteratorClasses.clear(); - associativeIteratorClasses.clear(); - mutableAssociativeIteratorClasses.clear(); -} - -/*! - This is called after all the source files (i.e., not the - header files) have been parsed. Currently nothing to do. - */ -void CppCodeParser::doneParsingSourceFiles() -{ - // contents moved to QdocDatabase::resolveIssues() -} - -static QSet<QString> topicCommands_; -/*! - Returns the set of strings reopresenting the topic commands. - */ -const QSet<QString>& CppCodeParser::topicCommands() -{ - if (topicCommands_.isEmpty()) { - topicCommands_ << COMMAND_CLASS - << COMMAND_DITAMAP - << COMMAND_ENUM - << COMMAND_EXAMPLE - << COMMAND_EXTERNALPAGE - << COMMAND_FILE - << COMMAND_FN - << COMMAND_GROUP - << COMMAND_HEADERFILE - << COMMAND_MACRO - << COMMAND_MODULE - << COMMAND_NAMESPACE - << COMMAND_PAGE - << COMMAND_PROPERTY - << COMMAND_TYPEDEF - << COMMAND_VARIABLE - << COMMAND_QMLTYPE - << COMMAND_QMLPROPERTY - << COMMAND_QMLPROPERTYGROUP - << COMMAND_QMLATTACHEDPROPERTY - << COMMAND_QMLSIGNAL - << COMMAND_QMLATTACHEDSIGNAL - << COMMAND_QMLMETHOD - << COMMAND_QMLATTACHEDMETHOD - << COMMAND_QMLBASICTYPE - << COMMAND_QMLMODULE - << COMMAND_JSTYPE - << COMMAND_JSPROPERTY - << COMMAND_JSPROPERTYGROUP - << COMMAND_JSATTACHEDPROPERTY - << COMMAND_JSSIGNAL - << COMMAND_JSATTACHEDSIGNAL - << COMMAND_JSMETHOD - << COMMAND_JSATTACHEDMETHOD - << COMMAND_JSBASICTYPE - << COMMAND_JSMODULE; - } - return topicCommands_; -} - -/*! - Process the topic \a command found in the \a doc with argument \a arg. - */ -Node* CppCodeParser::processTopicCommand(const Doc& doc, - const QString& command, - const ArgLocPair& arg) -{ - ExtraFuncData extra; - if (command == COMMAND_FN) { - QStringList parentPath; - FunctionNode *func = 0; - FunctionNode *clone = 0; - - if (!makeFunctionNode(arg.first, &parentPath, &clone, extra) && - !makeFunctionNode("void " + arg.first, &parentPath, &clone, extra)) { - doc.startLocation().warning(tr("Invalid syntax in '\\%1'").arg(COMMAND_FN)); - } - else { - func = qdb_->findFunctionNode(parentPath, clone); - if (func == 0) { - if (parentPath.isEmpty() && !lastPath_.isEmpty()) - func = qdb_->findFunctionNode(lastPath_, clone); - } - - /* - If the node was not found, then search for it in the - open C++ namespaces. We don't expect this search to - be necessary often. Nor do we expect it to succeed - very often. - */ - if (func == 0) - func = qdb_->findNodeInOpenNamespace(parentPath, clone); - - if (func == 0) { - doc.location().warning(tr("Cannot find '%1' in '\\%2' %3") - .arg(clone->name() + "(...)") - .arg(COMMAND_FN) - .arg(arg.first), - tr("I cannot find any function of that name with the " - "specified signature. Make sure that the signature " - "is identical to the declaration, including 'const' " - "qualifiers.")); - } - else - lastPath_ = parentPath; - if (func) { - func->borrowParameterNames(clone); - func->setParentPath(clone->parentPath()); - } - delete clone; - } - return func; - } - else if (command == COMMAND_MACRO) { - QStringList parentPath; - FunctionNode *func = 0; - - extra.root = qdb_->primaryTreeRoot(); - extra.isMacro = true; - if (makeFunctionNode(arg.first, &parentPath, &func, extra)) { - if (!parentPath.isEmpty()) { - doc.startLocation().warning(tr("Invalid syntax in '\\%1'").arg(COMMAND_MACRO)); - delete func; - func = 0; - } - else { - func->setMetaness(FunctionNode::MacroWithParams); - QVector<Parameter> params = func->parameters(); - for (int i = 0; i < params.size(); ++i) { - Parameter ¶m = params[i]; - if (param.name().isEmpty() && !param.dataType().isEmpty() - && param.dataType() != "...") - param = Parameter("", "", param.dataType()); - } - func->setParameters(params); - } - return func; - } - else if (QRegExp("[A-Za-z_][A-Za-z0-9_]+").exactMatch(arg.first)) { - func = new FunctionNode(qdb_->primaryTreeRoot(), arg.first); - func->setAccess(Node::Public); - func->setLocation(doc.startLocation()); - func->setMetaness(FunctionNode::MacroWithoutParams); - } - else { - doc.location().warning(tr("Invalid syntax in '\\%1'").arg(COMMAND_MACRO)); - - } - return func; - } - else if (nodeTypeMap.contains(command)) { - /* - We should only get in here if the command refers to - something that can appear in a C++ namespace, - i.e. a class, another namespace, an enum, a typedef, - a property or a variable. I think these are handled - this way to allow the writer to refer to the entity - without including the namespace qualifier. - */ - Node::NodeType type = nodeTypeMap[command]; - QStringList paths = arg.first.split(QLatin1Char(' ')); - QStringList path = paths[0].split("::"); - Node *node = 0; - - node = qdb_->findNodeInOpenNamespace(path, type); - if (node == 0) - node = qdb_->findNodeByNameAndType(path, type); - if (node == 0) { - doc.location().warning(tr("Cannot find '%1' specified with '\\%2' in any header file") - .arg(arg.first).arg(command)); - lastPath_ = path; - - } - else if (node->isAggregate()) { - if (type == Node::Namespace) { - NamespaceNode* ns = static_cast<NamespaceNode*>(node); - ns->markSeen(); - } - /* - This treats a class as a namespace. - */ - if ((type == Node::Class) || (type == Node::Namespace)) { - if (path.size() > 1) { - path.pop_back(); - QString ns = path.join("::"); - qdb_->insertOpenNamespace(ns); - } - } - } - return node; - } - else if (command == COMMAND_EXAMPLE) { - if (Config::generateExamples) { - ExampleNode* en = new ExampleNode(qdb_->primaryTreeRoot(), arg.first); - en->setLocation(doc.startLocation()); - createExampleFileNodes(en); - return en; - } - } - else if (command == COMMAND_EXTERNALPAGE) { - DocumentNode* dn = new DocumentNode(qdb_->primaryTreeRoot(), - arg.first, - Node::ExternalPage, - Node::ArticlePage); - dn->setLocation(doc.startLocation()); - return dn; - } - else if (command == COMMAND_FILE) { - DocumentNode* dn = new DocumentNode(qdb_->primaryTreeRoot(), - arg.first, - Node::File, - Node::NoPageType); - dn->setLocation(doc.startLocation()); - return dn; - } - else if (command == COMMAND_HEADERFILE) { - DocumentNode* dn = new DocumentNode(qdb_->primaryTreeRoot(), - arg.first, - Node::HeaderFile, - Node::ApiPage); - dn->setLocation(doc.startLocation()); - return dn; - } - else if (command == COMMAND_GROUP) { - CollectionNode* cn = qdb_->addGroup(arg.first); - cn->setLocation(doc.startLocation()); - cn->markSeen(); - return cn; - } - else if (command == COMMAND_MODULE) { - CollectionNode* cn = qdb_->addModule(arg.first); - cn->setLocation(doc.startLocation()); - cn->markSeen(); - return cn; - } - else if (command == COMMAND_QMLMODULE) { - QStringList blankSplit = arg.first.split(QLatin1Char(' ')); - CollectionNode* cn = qdb_->addQmlModule(blankSplit[0]); - cn->setLogicalModuleInfo(blankSplit); - cn->setLocation(doc.startLocation()); - cn->markSeen(); - return cn; - } - else if (command == COMMAND_JSMODULE) { - QStringList blankSplit = arg.first.split(QLatin1Char(' ')); - CollectionNode* cn = qdb_->addJsModule(blankSplit[0]); - cn->setLogicalModuleInfo(blankSplit); - cn->setLocation(doc.startLocation()); - cn->markSeen(); - return cn; - } - else if (command == COMMAND_PAGE) { - Node::PageType ptype = Node::ArticlePage; - QStringList args = arg.first.split(QLatin1Char(' ')); - if (args.size() > 1) { - QString t = args[1].toLower(); - if (t == "howto") - ptype = Node::HowToPage; - else if (t == "api") - ptype = Node::ApiPage; - else if (t == "example") - ptype = Node::ExamplePage; - else if (t == "overview") - ptype = Node::OverviewPage; - else if (t == "tutorial") - ptype = Node::TutorialPage; - else if (t == "faq") - ptype = Node::FAQPage; - else if (t == "ditamap") - ptype = Node::DitaMapPage; - } - DocumentNode* dn = 0; - if (ptype == Node::DitaMapPage) - dn = new DitaMapNode(qdb_->primaryTreeRoot(), args[0]); - else - dn = new DocumentNode(qdb_->primaryTreeRoot(), args[0], Node::Page, ptype); - dn->setLocation(doc.startLocation()); - return dn; - } - else if (command == COMMAND_DITAMAP) { - DocumentNode* dn = new DitaMapNode(qdb_->primaryTreeRoot(), arg.first); - dn->setLocation(doc.startLocation()); - return dn; - } - else if ((command == COMMAND_QMLTYPE) || (command == COMMAND_JSTYPE)) { - QmlTypeNode* qcn = new QmlTypeNode(qdb_->primaryTreeRoot(), arg.first); - if (command == COMMAND_JSTYPE) - qcn->setGenus(Node::JS); - qcn->setLocation(doc.startLocation()); - return qcn; - } - else if ((command == COMMAND_QMLBASICTYPE) || (command == COMMAND_JSBASICTYPE)) { - QmlBasicTypeNode* n = new QmlBasicTypeNode(qdb_->primaryTreeRoot(), arg.first); - if (command == COMMAND_JSBASICTYPE) - n->setGenus(Node::JS); - n->setLocation(doc.startLocation()); - return n; - } - else if ((command == COMMAND_QMLSIGNAL) || - (command == COMMAND_QMLMETHOD) || - (command == COMMAND_QMLATTACHEDSIGNAL) || - (command == COMMAND_QMLATTACHEDMETHOD) || - (command == COMMAND_JSSIGNAL) || - (command == COMMAND_JSMETHOD) || - (command == COMMAND_JSATTACHEDSIGNAL) || - (command == COMMAND_JSATTACHEDMETHOD)) { - QString module; - QString qmlTypeName; - QString type; - if (splitQmlMethodArg(arg.first, type, module, qmlTypeName)) { - QmlTypeNode* qmlType = qdb_->findQmlType(module, qmlTypeName); - if (qmlType) { - bool attached = false; - Node::NodeType nodeType = Node::QmlMethod; - if ((command == COMMAND_QMLSIGNAL) || - (command == COMMAND_JSSIGNAL)) - nodeType = Node::QmlSignal; - else if ((command == COMMAND_QMLATTACHEDSIGNAL) || - (command == COMMAND_JSATTACHEDSIGNAL)) { - nodeType = Node::QmlSignal; - attached = true; - } - else if ((command == COMMAND_QMLMETHOD) || - (command == COMMAND_JSMETHOD)) { - // do nothing - } - else if ((command == COMMAND_QMLATTACHEDMETHOD) || - (command == COMMAND_JSATTACHEDMETHOD)) - attached = true; - else - return 0; // never get here. - FunctionNode* fn = makeFunctionNode(doc, - arg.first, - qmlType, - nodeType, - attached, - command); - if (fn) { - fn->setLocation(doc.startLocation()); - if ((command == COMMAND_JSSIGNAL) || - (command == COMMAND_JSMETHOD) || - (command == COMMAND_JSATTACHEDSIGNAL) || - (command == COMMAND_JSATTACHEDMETHOD)) - fn->setGenus(Node::JS); - } - return fn; - } - } - } - return 0; -} - -/*! - A QML property group argument has the form... - - <QML-module>::<QML-type>::<name> - - This function splits the argument into those parts. - A <QML-module> is the QML equivalent of a C++ namespace. - So this function splits \a arg on "::" and stores the - parts in \a module, \a qmlTypeName, and \a name, and returns - true. If any part is not found, a qdoc warning is emitted - and false is returned. - */ -bool CppCodeParser::splitQmlPropertyGroupArg(const QString& arg, - QString& module, - QString& qmlTypeName, - QString& name) -{ - QStringList colonSplit = arg.split("::"); - if (colonSplit.size() == 3) { - module = colonSplit[0]; - qmlTypeName = colonSplit[1]; - name = colonSplit[2]; - return true; - } - QString msg = "Unrecognizable QML module/component qualifier for " + arg; - location().warning(tr(msg.toLatin1().data())); - return false; -} - -/*! - A QML property argument has the form... - - <type> <QML-type>::<name> - <type> <QML-module>::<QML-type>::<name> - - This function splits the argument into one of those - two forms. The three part form is the old form, which - was used before the creation of Qt Quick 2 and Qt - Components. A <QML-module> is the QML equivalent of a - C++ namespace. So this function splits \a arg on "::" - and stores the parts in \a type, \a module, \a qmlTypeName, - and \a name, and returns \c true. If any part other than - \a module is not found, a qdoc warning is emitted and - false is returned. - - \note The two QML types \e{Component} and \e{QtObject} - never have a module qualifier. - */ -bool CppCodeParser::splitQmlPropertyArg(const QString& arg, - QString& type, - QString& module, - QString& qmlTypeName, - QString& name) -{ - QStringList blankSplit = arg.split(QLatin1Char(' ')); - if (blankSplit.size() > 1) { - type = blankSplit[0]; - QStringList colonSplit(blankSplit[1].split("::")); - if (colonSplit.size() == 3) { - module = colonSplit[0]; - qmlTypeName = colonSplit[1]; - name = colonSplit[2]; - return true; - } - if (colonSplit.size() == 2) { - module.clear(); - qmlTypeName = colonSplit[0]; - name = colonSplit[1]; - return true; - } - QString msg = "Unrecognizable QML module/component qualifier for " + arg; - location().warning(tr(msg.toLatin1().data())); - } - else { - QString msg = "Missing property type for " + arg; - location().warning(tr(msg.toLatin1().data())); - } - return false; -} - -/*! - A QML signal or method argument has the form... - - <type> <QML-type>::<name>(<param>, <param>, ...) - <type> <QML-module>::<QML-type>::<name>(<param>, <param>, ...) - - This function splits the \a{arg}ument into one of those - two forms, sets \a type, \a module, and \a qmlTypeName, - and returns true. If the argument doesn't match either - form, an error message is emitted and false is returned. - - \note The two QML types \e{Component} and \e{QtObject} never - have a module qualifier. - */ -bool CppCodeParser::splitQmlMethodArg(const QString& arg, - QString& type, - QString& module, - QString& qmlTypeName) -{ - QString name; - int leftParen = arg.indexOf(QChar('(')); - if (leftParen > 0) - name = arg.left(leftParen); - else - name = arg; - int firstBlank = name.indexOf(QChar(' ')); - if (firstBlank > 0) { - type = name.left(firstBlank); - name = name.right(name.length() - firstBlank - 1); - } - else - type.clear(); - - QStringList colonSplit(name.split("::")); - if (colonSplit.size() > 1) { - if (colonSplit.size() > 2) { - module = colonSplit[0]; - qmlTypeName = colonSplit[1]; - } - else { - module.clear(); - qmlTypeName = colonSplit[0]; - } - return true; - } - QString msg = "Unrecognizable QML module/component qualifier for " + arg; - location().warning(tr(msg.toLatin1().data())); - return false; -} - -/*! - Process the topic \a command group found in the \a doc with arguments \a args. - - Currently, this function is called only for \e{qmlproperty} - and \e{qmlattachedproperty}. - */ -void CppCodeParser::processQmlProperties(const Doc& doc, - NodeList& nodes, - DocList& docs, - bool jsProps) -{ - QString arg; - QString type; - QString topic; - QString module; - QString qmlTypeName; - QString property; - QmlPropertyNode* qpn = 0; - QmlTypeNode* qmlType = 0; - QmlPropertyGroupNode* qpgn = 0; - - Topic qmlPropertyGroupTopic; - const TopicList& topics = doc.topicsUsed(); - for (int i=0; i<topics.size(); ++i) { - if ((topics.at(i).topic == COMMAND_QMLPROPERTYGROUP) || - (topics.at(i).topic == COMMAND_JSPROPERTYGROUP)) { - qmlPropertyGroupTopic = topics.at(i); - break; - } - } - if (qmlPropertyGroupTopic.isEmpty() && topics.size() > 1) { - qmlPropertyGroupTopic = topics.at(0); - if (jsProps) - qmlPropertyGroupTopic.topic = COMMAND_JSPROPERTYGROUP; - else - qmlPropertyGroupTopic.topic = COMMAND_QMLPROPERTYGROUP; - arg = qmlPropertyGroupTopic.args; - if (splitQmlPropertyArg(arg, type, module, qmlTypeName, property)) { - int i = property.indexOf('.'); - if (i != -1) { - property = property.left(i); - qmlPropertyGroupTopic.args = module + "::" + qmlTypeName + "::" + property; - doc.location().warning(tr("No QML property group command found; using \\%1 %2") - .arg(COMMAND_QMLPROPERTYGROUP).arg(qmlPropertyGroupTopic.args)); - } - else { - /* - Assumption: No '.' in the property name - means there is no property group. - */ - qmlPropertyGroupTopic.clear(); - } - } - } - - if (!qmlPropertyGroupTopic.isEmpty()) { - arg = qmlPropertyGroupTopic.args; - if (splitQmlPropertyGroupArg(arg, module, qmlTypeName, property)) { - qmlType = qdb_->findQmlType(module, qmlTypeName); - if (qmlType) { - qpgn = new QmlPropertyGroupNode(qmlType, property); - qpgn->setLocation(doc.startLocation()); - if (jsProps) - qpgn->setGenus(Node::JS); - nodes.append(qpgn); - docs.append(doc); - } - } - } - for (int i=0; i<topics.size(); ++i) { - if (topics.at(i).topic == COMMAND_QMLPROPERTYGROUP) { - continue; - } - topic = topics.at(i).topic; - arg = topics.at(i).args; - if ((topic == COMMAND_QMLPROPERTY) || (topic == COMMAND_QMLATTACHEDPROPERTY) || - (topic == COMMAND_JSPROPERTY) || (topic == COMMAND_JSATTACHEDPROPERTY)) { - bool attached = ((topic == COMMAND_QMLATTACHEDPROPERTY) || - (topic == COMMAND_JSATTACHEDPROPERTY)); - if (splitQmlPropertyArg(arg, type, module, qmlTypeName, property)) { - qmlType = qdb_->findQmlType(module, qmlTypeName); - if (qmlType) { - if (qmlType->hasQmlProperty(property, attached) != 0) { - QString msg = tr("QML property documented multiple times: '%1'").arg(arg); - doc.startLocation().warning(msg); - } - else if (qpgn) { - qpn = new QmlPropertyNode(qpgn, property, type, attached); - qpn->setLocation(doc.startLocation()); - if (jsProps) - qpn->setGenus(Node::JS); - } - else { - qpn = new QmlPropertyNode(qmlType, property, type, attached); - qpn->setLocation(doc.startLocation()); - if (jsProps) - qpn->setGenus(Node::JS); - nodes.append(qpn); - docs.append(doc); - } - } - } - } else if (qpgn) { - doc.startLocation().warning( - tr("Invalid use of '\\%1'; not allowed in a '\\%2'").arg( - topic, qmlPropertyGroupTopic.topic)); - } - } -} - -static QSet<QString> otherMetaCommands_; -/*! - Returns the set of strings representing the common metacommands - plus some other metacommands. - */ -const QSet<QString>& CppCodeParser::otherMetaCommands() -{ - if (otherMetaCommands_.isEmpty()) { - otherMetaCommands_ = commonMetaCommands(); - otherMetaCommands_ << COMMAND_INHEADERFILE - << COMMAND_OVERLOAD - << COMMAND_REIMP - << COMMAND_RELATES - << COMMAND_CONTENTSPAGE - << COMMAND_NEXTPAGE - << COMMAND_PREVIOUSPAGE - << COMMAND_INDEXPAGE - << COMMAND_STARTPAGE - << COMMAND_QMLINHERITS - << COMMAND_QMLINSTANTIATES - << COMMAND_QMLDEFAULT - << COMMAND_QMLREADONLY - << COMMAND_QMLABSTRACT - << COMMAND_ABSTRACT; - } - return otherMetaCommands_; -} - -/*! - Process the metacommand \a command in the context of the - \a node associated with the topic command and the \a doc. - \a arg is the argument to the metacommand. - */ -void CppCodeParser::processOtherMetaCommand(const Doc& doc, - const QString& command, - const ArgLocPair& argLocPair, - Node *node) -{ - QString arg = argLocPair.first; - if (command == COMMAND_INHEADERFILE) { - if (node != 0 && node->isAggregate()) { - ((Aggregate *) node)->addInclude(arg); - } - else { - doc.location().warning(tr("Ignored '\\%1'").arg(COMMAND_INHEADERFILE)); - } - } - else if (command == COMMAND_OVERLOAD) { - if (node && node->isFunction()) - ((FunctionNode *) node)->setOverloadFlag(true); - else - doc.location().warning(tr("Ignored '\\%1'").arg(COMMAND_OVERLOAD)); - } - else if (command == COMMAND_REIMP) { - if (node != 0 && node->parent() && !node->parent()->isInternal()) { - if (node->type() == Node::Function) { - FunctionNode *func = (FunctionNode *) node; - const FunctionNode *from = func->reimplementedFrom(); - if (from == 0) { - doc.location().warning(tr("Cannot find base function for '\\%1' in %2()") - .arg(COMMAND_REIMP).arg(node->name()), - tr("The function either doesn't exist in any " - "base class with the same signature or it " - "exists but isn't virtual.")); - } - /* - Ideally, we would enable this check to warn whenever - \reimp is used incorrectly, and only make the node - internal if the function is a reimplementation of - another function in a base class. - */ - else if (from->access() == Node::Private - || from->parent()->access() == Node::Private) { - doc.location().warning(tr("'\\%1' in %2() should be '\\internal' " - "because its base function is private " - "or internal").arg(COMMAND_REIMP).arg(node->name())); - } - func->setReimplemented(true); - } - else { - doc.location().warning(tr("Ignored '\\%1' in %2").arg(COMMAND_REIMP).arg(node->name())); - } - } - } - else if (command == COMMAND_RELATES) { - QStringList path = arg.split("::"); - Node* n = qdb_->findRelatesNode(path); - if (!n) { - // Store just a string to write to the index file - if (Generator::preparing()) - node->setRelates(arg); - else - doc.location().warning(tr("Cannot find '%1' in '\\%2'").arg(arg).arg(COMMAND_RELATES)); - - } - else if (node->parent() != n) - node->setRelates(static_cast<Aggregate*>(n)); - else - doc.location().warning(tr("Invalid use of '\\%1' (already a member of '%2')") - .arg(COMMAND_RELATES, arg)); - } - else if (command == COMMAND_CONTENTSPAGE) { - setLink(node, Node::ContentsLink, arg); - } - else if (command == COMMAND_NEXTPAGE) { - setLink(node, Node::NextLink, arg); - } - else if (command == COMMAND_PREVIOUSPAGE) { - setLink(node, Node::PreviousLink, arg); - } - else if (command == COMMAND_INDEXPAGE) { - setLink(node, Node::IndexLink, arg); - } - else if (command == COMMAND_STARTPAGE) { - setLink(node, Node::StartLink, arg); - } - else if (command == COMMAND_QMLINHERITS) { - if (node->name() == arg) - doc.location().warning(tr("%1 tries to inherit itself").arg(arg)); - else if (node->isQmlType() || node->isJsType()) { - QmlTypeNode* qmlType = static_cast<QmlTypeNode*>(node); - qmlType->setQmlBaseName(arg); - QmlTypeNode::addInheritedBy(arg,node); - } - } - else if (command == COMMAND_QMLINSTANTIATES) { - if (node->isQmlType() || node->isJsType()) { - ClassNode* classNode = qdb_->findClassNode(arg.split("::")); - if (classNode) - node->setClassNode(classNode); - else - doc.location().warning(tr("C++ class %1 not found: \\instantiates %1").arg(arg)); - } - else - doc.location().warning(tr("\\instantiates is only allowed in \\qmltype")); - } - else if (command == COMMAND_QMLDEFAULT) { - if (node->type() == Node::QmlProperty) { - QmlPropertyNode* qpn = static_cast<QmlPropertyNode*>(node); - qpn->setDefault(); - } - else if (node->type() == Node::QmlPropertyGroup) { - QmlPropertyGroupNode* qpgn = static_cast<QmlPropertyGroupNode*>(node); - NodeList::ConstIterator p = qpgn->childNodes().constBegin(); - while (p != qpgn->childNodes().constEnd()) { - if ((*p)->type() == Node::QmlProperty) { - QmlPropertyNode* qpn = static_cast<QmlPropertyNode*>(*p); - qpn->setDefault(); - } - ++p; - } - } - } - else if (command == COMMAND_QMLREADONLY) { - if (node->type() == Node::QmlProperty) { - QmlPropertyNode* qpn = static_cast<QmlPropertyNode*>(node); - qpn->setReadOnly(1); - } - else if (node->type() == Node::QmlPropertyGroup) { - QmlPropertyGroupNode* qpgn = static_cast<QmlPropertyGroupNode*>(node); - NodeList::ConstIterator p = qpgn->childNodes().constBegin(); - while (p != qpgn->childNodes().constEnd()) { - if ((*p)->type() == Node::QmlProperty) { - QmlPropertyNode* qpn = static_cast<QmlPropertyNode*>(*p); - qpn->setReadOnly(1); - } - ++p; - } - } - } - else if ((command == COMMAND_QMLABSTRACT) || (command == COMMAND_ABSTRACT)) { - if (node->isQmlType() || node->isJsType()) - node->setAbstract(true); - } - else { - processCommonMetaCommand(doc.location(),command,argLocPair,node); - } -} - -/*! - The topic command has been processed resulting in the \a doc - and \a node passed in here. Process the other meta commands, - which are found in \a doc, in the context of the topic \a node. - */ -void CppCodeParser::processOtherMetaCommands(const Doc& doc, Node *node) -{ - const QSet<QString> metaCommands = doc.metaCommandsUsed(); - QSet<QString>::ConstIterator cmd = metaCommands.constBegin(); - while (cmd != metaCommands.constEnd()) { - ArgList args = doc.metaCommandArgs(*cmd); - ArgList::ConstIterator arg = args.constBegin(); - while (arg != args.constEnd()) { - processOtherMetaCommand(doc, *cmd, *arg, node); - ++arg; - } - ++cmd; - } -} - -/*! - Resets the C++ code parser to its default initialized state. - */ -void CppCodeParser::reset() -{ - tokenizer = 0; - tok = 0; - access = Node::Public; - metaness_ = FunctionNode::Plain; - lastPath_.clear(); - physicalModuleName.clear(); -} - -/*! - Get the next token from the file being parsed and store it - in the token variable. - */ -void CppCodeParser::readToken() -{ - tok = tokenizer->getToken(); -} - -/*! - Return the current location in the file being parsed, - i.e. the file name, line number, and column number. - */ -const Location& CppCodeParser::location() -{ - return tokenizer->location(); -} - -/*! - Return the previous string read from the file being parsed. - */ -QString CppCodeParser::previousLexeme() -{ - return tokenizer->previousLexeme(); -} - -/*! - Return the current string string from the file being parsed. - */ -QString CppCodeParser::lexeme() -{ - return tokenizer->lexeme(); -} - -bool CppCodeParser::match(int target) -{ - if (tok == target) { - readToken(); - return true; - } - return false; -} - -/*! - Skip to \a target. If \a target is found before the end - of input, return true. Otherwise return false. - */ -bool CppCodeParser::skipTo(int target) -{ - while ((tok != Tok_Eoi) && (tok != target)) - readToken(); - return tok == target; -} - -/*! - If the current token is one of the keyword thingees that - are used in Qt, skip over it to the next token and return - true. Otherwise just return false without reading the - next token. - */ -bool CppCodeParser::matchCompat() -{ - switch (tok) { - case Tok_QT_COMPAT: - case Tok_QT_COMPAT_CONSTRUCTOR: - case Tok_QT_DEPRECATED: - case Tok_QT_MOC_COMPAT: - case Tok_QT3_SUPPORT: - case Tok_QT3_SUPPORT_CONSTRUCTOR: - case Tok_QT3_MOC_SUPPORT: - readToken(); - return true; - default: - return false; - } -} - -bool CppCodeParser::matchModuleQualifier(QString& name) -{ - bool matches = (lexeme() == QString('.')); - if (matches) { - do { - name += lexeme(); - readToken(); - } while ((tok == Tok_Ident) || (lexeme() == QString('.'))); - } - return matches; -} - -bool CppCodeParser::matchTemplateAngles(CodeChunk *dataType) -{ - bool matches = (tok == Tok_LeftAngle); - if (matches) { - int leftAngleDepth = 0; - int parenAndBraceDepth = 0; - do { - if (tok == Tok_LeftAngle) { - leftAngleDepth++; - } - else if (tok == Tok_RightAngle) { - leftAngleDepth--; - } - else if (tok == Tok_LeftParen || tok == Tok_LeftBrace) { - ++parenAndBraceDepth; - } - else if (tok == Tok_RightParen || tok == Tok_RightBrace) { - if (--parenAndBraceDepth < 0) - return false; - } - if (dataType != 0) - dataType->append(lexeme()); - readToken(); - } while (leftAngleDepth > 0 && tok != Tok_Eoi); - } - return matches; -} - -/* - This function is no longer used. - */ -bool CppCodeParser::matchTemplateHeader() -{ - readToken(); - return matchTemplateAngles(); -} - -bool CppCodeParser::matchDataType(CodeChunk *dataType, QString *var) -{ - /* - This code is really hard to follow... sorry. The loop is there to match - Alpha::Beta::Gamma::...::Omega. - */ - for (;;) { - bool virgin = true; - - if (tok != Tok_Ident) { - /* - There is special processing for 'Foo::operator int()' - and such elsewhere. This is the only case where we - return something with a trailing gulbrandsen ('Foo::'). - */ - if (tok == Tok_operator) - return true; - - /* - People may write 'const unsigned short' or - 'short unsigned const' or any other permutation. - */ - while (match(Tok_const) || match(Tok_volatile)) - dataType->append(previousLexeme()); - while (match(Tok_signed) || match(Tok_unsigned) || - match(Tok_short) || match(Tok_long) || match(Tok_int64)) { - dataType->append(previousLexeme()); - virgin = false; - } - while (match(Tok_const) || match(Tok_volatile)) - dataType->append(previousLexeme()); - - if (match(Tok_Tilde)) - dataType->append(previousLexeme()); - } - - if (virgin) { - if (match(Tok_Ident)) { - /* - This is a hack until we replace this "parser" - with the real one used in Qt Creator. - */ - if (!inMacroCommand_ && lexeme() == "(" && - ((previousLexeme() == "QT_PREPEND_NAMESPACE") || (previousLexeme() == "NS"))) { - readToken(); - readToken(); - dataType->append(previousLexeme()); - readToken(); - } - else - dataType->append(previousLexeme()); - } - else if (match(Tok_void) || match(Tok_int) || match(Tok_char) || - match(Tok_double) || match(Tok_Ellipsis)) { - dataType->append(previousLexeme()); - } - else { - return false; - } - } - else if (match(Tok_int) || match(Tok_char) || match(Tok_double)) { - dataType->append(previousLexeme()); - } - - matchTemplateAngles(dataType); - - while (match(Tok_const) || match(Tok_volatile)) - dataType->append(previousLexeme()); - - if (match(Tok_Gulbrandsen)) - dataType->append(previousLexeme()); - else - break; - } - - while (match(Tok_Ampersand) || match(Tok_Aster) || match(Tok_const) || - match(Tok_Caret)) - dataType->append(previousLexeme()); - - if (match(Tok_LeftParenAster)) { - /* - A function pointer. This would be rather hard to handle without a - tokenizer hack, because a type can be followed with a left parenthesis - in some cases (e.g., 'operator int()'). The tokenizer recognizes '(*' - as a single token. - */ - dataType->append(previousLexeme()); - dataType->appendHotspot(); - if (var != 0 && match(Tok_Ident)) - *var = previousLexeme(); - if (!match(Tok_RightParen) || tok != Tok_LeftParen) { - return false; - } - dataType->append(previousLexeme()); - - int parenDepth0 = tokenizer->parenDepth(); - while (tokenizer->parenDepth() >= parenDepth0 && tok != Tok_Eoi) { - dataType->append(lexeme()); - readToken(); - } - if (match(Tok_RightParen)) - dataType->append(previousLexeme()); - } - else { - /* - The common case: Look for an optional identifier, then for - some array brackets. - */ - dataType->appendHotspot(); - - if (var != 0) { - if (match(Tok_Ident)) { - *var = previousLexeme(); - } - else if (match(Tok_Comment)) { - /* - A neat hack: Commented-out parameter names are - recognized by qdoc. It's impossible to illustrate - here inside a C-style comment, because it requires - an asterslash. It's also impossible to illustrate - inside a C++-style comment, because the explanation - does not fit on one line. - */ - if (varComment.exactMatch(previousLexeme())) - *var = varComment.cap(1); - } - } - - if (tok == Tok_LeftBracket) { - int bracketDepth0 = tokenizer->bracketDepth(); - while ((tokenizer->bracketDepth() >= bracketDepth0 && - tok != Tok_Eoi) || - tok == Tok_RightBracket) { - dataType->append(lexeme()); - readToken(); - } - } - } - return true; -} - -/*! - Parse the next function parameter, if there is one, and - append it to parameter vector \a pvect. Return true if - a parameter is parsed and appended to \a pvect. - Otherwise return false. - */ -bool CppCodeParser::matchParameter(QVector<Parameter>& pvect, bool& isQPrivateSignal) -{ - if (match(Tok_QPrivateSignal)) { - isQPrivateSignal = true; - return true; - } - - Parameter p; - CodeChunk chunk; - if (!matchDataType(&chunk, &p.name_)) { - return false; - } - p.dataType_ = chunk.toString(); - chunk.clear(); - match(Tok_Comment); - if (match(Tok_Equal)) { - int pdepth = tokenizer->parenDepth(); - while (tokenizer->parenDepth() >= pdepth && - (tok != Tok_Comma || (tokenizer->parenDepth() > pdepth)) && - tok != Tok_Eoi) { - chunk.append(lexeme()); - readToken(); - } - } - p.defaultValue_ = chunk.toString(); - pvect.append(p); - return true; -} - -/*! - If the current token is any of several function modifiers, - return that token value after reading the next token. If it - is not one of the function modieifer tokens, return -1 but - don\t read the next token. - */ -int CppCodeParser::matchFunctionModifier() -{ - switch (tok) { - case Tok_friend: - case Tok_inline: - case Tok_explicit: - case Tok_static: - case Tok_QT_DEPRECATED: - readToken(); - return tok; - case Tok_QT_COMPAT: - case Tok_QT_COMPAT_CONSTRUCTOR: - case Tok_QT_MOC_COMPAT: - case Tok_QT3_SUPPORT: - case Tok_QT3_SUPPORT_CONSTRUCTOR: - case Tok_QT3_MOC_SUPPORT: - readToken(); - return Tok_QT_COMPAT; - default: - break; - } - return -1; -} - -bool CppCodeParser::matchFunctionDecl(Aggregate *parent, - QStringList *parentPathPtr, - FunctionNode **funcPtr, - const QString &templateStuff, - ExtraFuncData& extra) -{ - CodeChunk returnType; - QStringList parentPath; - QString name; - - bool matched_QT_DEPRECATED = false; - bool matched_friend = false; - bool matched_static = false; - bool matched_inline = false; - bool matched_explicit = false; - bool matched_compat = false; - - int token = tok; - while (token != -1) { - switch (token) { - case Tok_friend: - matched_friend = true; - break; - case Tok_inline: - matched_inline = true; - break; - case Tok_explicit: - matched_explicit = true; - break; - case Tok_static: - matched_static = true; - break; - case Tok_QT_DEPRECATED: - // no break here. - matched_QT_DEPRECATED = true; - case Tok_QT_COMPAT: - matched_compat = true; - break; - } - token = matchFunctionModifier(); - } - - FunctionNode::Virtualness virtuality = FunctionNode::NonVirtual; - if (match(Tok_virtual)) { - virtuality = FunctionNode::NormalVirtual; - if (!matched_compat) - matched_compat = matchCompat(); - } - - if (!matchDataType(&returnType)) { - if (tokenizer->parsingFnOrMacro() - && (match(Tok_Q_DECLARE_FLAGS) || - match(Tok_Q_PROPERTY) || - match(Tok_Q_PRIVATE_PROPERTY))) - returnType = CodeChunk(previousLexeme()); - else { - return false; - } - } - - if (returnType.toString() == "QBool") - returnType = CodeChunk("bool"); - - if (!matched_compat) - matched_compat = matchCompat(); - - if (tok == Tok_operator && - (returnType.toString().isEmpty() || - returnType.toString().endsWith("::"))) { - // 'QString::operator const char *()' - parentPath = returnType.toString().split(sep); - parentPath.removeAll(QString()); - returnType = CodeChunk(); - readToken(); - - CodeChunk restOfName; - if (tok != Tok_Tilde && matchDataType(&restOfName)) { - name = "operator " + restOfName.toString(); - } - else { - name = previousLexeme() + lexeme(); - readToken(); - while (tok != Tok_LeftParen && tok != Tok_Eoi) { - name += lexeme(); - readToken(); - } - } - if (tok != Tok_LeftParen) { - return false; - } - } - else if (tok == Tok_LeftParen) { - // constructor or destructor - parentPath = returnType.toString().split(sep); - if (!parentPath.isEmpty()) { - name = parentPath.last(); - parentPath.erase(parentPath.end() - 1); - } - returnType = CodeChunk(); - } - else { - while (match(Tok_Ident)) { - name = previousLexeme(); - /* - This is a hack to let QML module identifiers through. - */ - matchModuleQualifier(name); - matchTemplateAngles(); - - if (match(Tok_Gulbrandsen)) - parentPath.append(name); - else - break; - } - - if (tok == Tok_operator) { - name = lexeme(); - readToken(); - while (tok != Tok_Eoi) { - name += lexeme(); - readToken(); - if (tok == Tok_LeftParen) - break; - } - } - if (parent && (tok == Tok_Semicolon || - tok == Tok_LeftBracket || - tok == Tok_Colon) - && access != Node::Private) { - if (tok == Tok_LeftBracket) { - returnType.appendHotspot(); - - int bracketDepth0 = tokenizer->bracketDepth(); - while ((tokenizer->bracketDepth() >= bracketDepth0 && - tok != Tok_Eoi) || - tok == Tok_RightBracket) { - returnType.append(lexeme()); - readToken(); - } - if (tok != Tok_Semicolon) { - return false; - } - } - else if (tok == Tok_Colon) { - returnType.appendHotspot(); - - while (tok != Tok_Semicolon && tok != Tok_Eoi) { - returnType.append(lexeme()); - readToken(); - } - if (tok != Tok_Semicolon) { - return false; - } - } - - VariableNode *var = new VariableNode(parent, name); - var->setAccess(access); - var->setLocation(location()); - var->setLeftType(returnType.left()); - var->setRightType(returnType.right()); - if (matched_compat) - var->setStatus(Node::Compat); - var->setStatic(matched_static); - return false; - } - if (tok != Tok_LeftParen) - return false; - } - readToken(); - - // A left paren was seen. Parse the parameters - bool isQPrivateSignal = false; - QVector<Parameter> pvect; - if (tok != Tok_RightParen) { - do { - if (!matchParameter(pvect, isQPrivateSignal)) - return false; - } while (match(Tok_Comma)); - } - // The parameters must end with a right paren - if (!match(Tok_RightParen)) - return false; - - // look for const - bool matchedConst = match(Tok_const); - - // look for 0 indicating pure virtual - if (match(Tok_Equal) && match(Tok_Number)) - virtuality = FunctionNode::PureVirtual; - - // look for colon indicating ctors which must be skipped - if (match(Tok_Colon)) { - while (tok != Tok_LeftBrace && tok != Tok_Eoi) - readToken(); - } - - // If no ';' expect a body, which must be skipped. - bool body_expected = false; - bool body_present = false; - if (!match(Tok_Semicolon) && tok != Tok_Eoi) { - body_expected = true; - int nesting = tokenizer->braceDepth(); - if (!match(Tok_LeftBrace)) - return false; - // skip the body - while (tokenizer->braceDepth() >= nesting && tok != Tok_Eoi) - readToken(); - body_present = true; - match(Tok_RightBrace); - } - - FunctionNode *func = 0; - bool createFunctionNode = false; - if (parsingHeaderFile_) { - if (matched_friend) { - if (matched_inline) { - // nothing yet - } - if (body_present) { - if (body_expected) { - // nothing yet - } - createFunctionNode = true; - if (parent && parent->parent()) - parent = parent->parent(); - else - return false; - } - } - else - createFunctionNode = true; - } - else - createFunctionNode = true; - - if (createFunctionNode) { - func = new FunctionNode(extra.type, parent, name, extra.isAttached); - if (matched_friend) - access = Node::Public; - func->setAccess(access); - func->setLocation(location()); - func->setReturnType(returnType.toString()); - func->setParentPath(parentPath); - func->setTemplateStuff(templateStuff); - if (matched_compat) - func->setStatus(Node::Compat); - if (matched_QT_DEPRECATED) - func->setStatus(Node::Deprecated); - if (matched_explicit) { /* What can be done? */ } - func->setMetaness(metaness_); - if (parent) { - if (name == parent->name()) - func->setMetaness(FunctionNode::Ctor); - else if (name.startsWith(QLatin1Char('~'))) - func->setMetaness(FunctionNode::Dtor); - } - func->setStatic(matched_static); - func->setConst(matchedConst); - func->setVirtualness(virtuality); - if (isQPrivateSignal) - func->setPrivateSignal(); - if (!pvect.isEmpty()) { - func->setParameters(pvect); - } - } - if (parentPathPtr != 0) - *parentPathPtr = parentPath; - if (funcPtr != 0) - *funcPtr = func; - return true; -} - -bool CppCodeParser::matchBaseSpecifier(ClassNode *classe, bool isClass) -{ - Node::Access access; - - switch (tok) { - case Tok_public: - access = Node::Public; - readToken(); - break; - case Tok_protected: - access = Node::Protected; - readToken(); - break; - case Tok_private: - access = Node::Private; - readToken(); - break; - default: - access = isClass ? Node::Private : Node::Public; - } - - if (tok == Tok_virtual) - readToken(); - - CodeChunk baseClass; - if (!matchDataType(&baseClass)) - return false; - - classe->addUnresolvedBaseClass(access, baseClass.toPath(), baseClass.toString()); - return true; -} - -bool CppCodeParser::matchBaseList(ClassNode *classe, bool isClass) -{ - for (;;) { - if (!matchBaseSpecifier(classe, isClass)) - return false; - if (tok == Tok_LeftBrace) - return true; - if (!match(Tok_Comma)) - return false; - } -} - -/*! - Parse a C++ class, union, or struct declaration. - - This function only handles one level of class nesting, but that is - sufficient for Qt because there are no cases of class nesting more - than one level deep. - */ -bool CppCodeParser::matchClassDecl(Aggregate *parent, - const QString &templateStuff) -{ - bool isClass = (tok == Tok_class); - readToken(); - - bool compat = matchCompat(); - - if (tok != Tok_Ident) - return false; - while (tok == Tok_Ident) - readToken(); - if (tok == Tok_Gulbrandsen) { - Node* n = parent->findChildNode(previousLexeme(),Node::Class); - if (n) { - parent = static_cast<Aggregate*>(n); - if (parent) { - readToken(); - if (tok != Tok_Ident) - return false; - readToken(); - } - } - } - if (tok != Tok_Colon && tok != Tok_LeftBrace) - return false; - - /* - So far, so good. We have 'class Foo {' or 'class Foo :'. - This is enough to recognize a class definition. - */ - ClassNode *classe = new ClassNode(parent, previousLexeme()); - classe->setAccess(access); - classe->setLocation(location()); - if (compat) - classe->setStatus(Node::Compat); - if (!physicalModuleName.isEmpty()) - classe->setPhysicalModuleName(physicalModuleName); - classe->setTemplateStuff(templateStuff); - - if (match(Tok_Colon) && !matchBaseList(classe, isClass)) - return false; - if (!match(Tok_LeftBrace)) - return false; - - Node::Access outerAccess = access; - access = isClass ? Node::Private : Node::Public; - FunctionNode::Metaness outerMetaness = metaness_; - metaness_ = FunctionNode::Plain; - - bool matches = (matchDeclList(classe) && match(Tok_RightBrace) && - match(Tok_Semicolon)); - access = outerAccess; - metaness_ = outerMetaness; - return matches; -} - -bool CppCodeParser::matchNamespaceDecl(Aggregate *parent) -{ - readToken(); // skip 'namespace' - if (tok != Tok_Ident) - return false; - while (tok == Tok_Ident) - readToken(); - if (tok != Tok_LeftBrace) - return false; - - /* - So far, so good. We have 'namespace Foo {'. - */ - QString namespaceName = previousLexeme(); - NamespaceNode* ns = 0; - if (parent) - ns = static_cast<NamespaceNode*>(parent->findChildNode(namespaceName, Node::Namespace)); - if (!ns) { - ns = new NamespaceNode(parent, namespaceName); - ns->setAccess(access); - ns->setLocation(location()); - } - - readToken(); // skip '{' - bool matched = matchDeclList(ns); - return matched && match(Tok_RightBrace); -} - -/*! - Match a C++ \c using clause. Return \c true if the match - is successful. Otherwise false. - - If the \c using clause is for a namespace, an open namespace - <is inserted for qdoc to look in to find things. - - If the \c using clause is a base class member function, the - member function is added to \a parent as an unresolved - \c using clause. - */ -bool CppCodeParser::matchUsingDecl(Aggregate* parent) -{ - bool usingNamespace = false; - readToken(); // skip 'using' - - if (tok == Tok_namespace) { - usingNamespace = true; - readToken(); - } - - int openLeftAngles = 0; - int openLeftParens = 0; - bool usingOperator = false; - QString name; - while (tok != Tok_Semicolon) { - if ((tok != Tok_Ident) && (tok != Tok_Gulbrandsen)) { - if (tok == Tok_LeftAngle) { - ++openLeftAngles; - } - else if (tok == Tok_RightAngle) { - if (openLeftAngles <= 0) - return false; - --openLeftAngles; - } - else if (tok == Tok_Comma) { - if (openLeftAngles <= 0) - return false; - } - else if (tok == Tok_operator) { - usingOperator = true; - } - else if (tok == Tok_SomeOperator) { - if (!usingOperator) - return false; - } - else if (tok == Tok_LeftParen) { - ++openLeftParens; - } - else if (tok == Tok_RightParen) { - if (openLeftParens <= 0) - return false; - --openLeftParens; - } - else { - return false; - } - } - name += lexeme(); - readToken(); - } - - if (usingNamespace) { - // 'using namespace Foo;'. - qdb_->insertOpenNamespace(name); - } - else if (parent && parent->isClass()) { - ClassNode* cn = static_cast<ClassNode*>(parent); - cn->addUnresolvedUsingClause(name); - } - return true; -} - -bool CppCodeParser::matchEnumItem(Aggregate *parent, EnumNode *enume) -{ - if (!match(Tok_Ident)) - return false; - - QString name = previousLexeme(); - CodeChunk val; - int parenLevel = 0; - - if (match(Tok_Equal)) { - while (tok != Tok_RightBrace && tok != Tok_Eoi) { - if (tok == Tok_LeftParen) - parenLevel++; - else if (tok == Tok_RightParen) - parenLevel--; - else if (tok == Tok_Comma) { - if (parenLevel <= 0) - break; - } - val.append(lexeme()); - readToken(); - } - } - - if (enume) { - QString strVal = val.toString(); - if (strVal.isEmpty()) { - if (enume->items().isEmpty()) { - strVal = "0"; - } - else { - QString last = enume->items().last().value(); - bool ok; - int n = last.toInt(&ok); - if (ok) { - if (last.startsWith(QLatin1Char('0')) && last.size() > 1) { - if (last.startsWith("0x") || last.startsWith("0X")) - strVal = last.left(2) + QString::number(n + 1, 16); - else - strVal = QLatin1Char('0') + QString::number(n + 1, 8); - } - else - strVal = QString::number(n + 1); - } - } - } - - enume->addItem(EnumItem(name, strVal)); - } - else { - VariableNode *var = new VariableNode(parent, name); - var->setAccess(access); - var->setLocation(location()); - var->setLeftType("const int"); - var->setStatic(true); - } - return true; -} - -bool CppCodeParser::matchEnumDecl(Aggregate *parent) -{ - QString name; - - if (!match(Tok_enum)) - return false; - if (match(Tok_Ident)) - name = previousLexeme(); - if (tok != Tok_LeftBrace) - return false; - - EnumNode *enume = 0; - - if (!name.isEmpty()) { - enume = new EnumNode(parent, name); - enume->setAccess(access); - enume->setLocation(location()); - } - - readToken(); - - if (!matchEnumItem(parent, enume)) - return false; - - while (match(Tok_Comma)) { - if (!matchEnumItem(parent, enume)) - return false; - } - return match(Tok_RightBrace) && match(Tok_Semicolon); -} - -bool CppCodeParser::matchTypedefDecl(Aggregate *parent) -{ - CodeChunk dataType; - QString name; - - if (!match(Tok_typedef)) - return false; - if (!matchDataType(&dataType, &name)) - return false; - if (!match(Tok_Semicolon)) - return false; - - if (parent && !parent->findChildNode(name, Node::Typedef)) { - TypedefNode* td = new TypedefNode(parent, name); - td->setAccess(access); - td->setLocation(location()); - } - return true; -} - -bool CppCodeParser::matchProperty(Aggregate *parent) -{ - int expected_tok = Tok_LeftParen; - if (match(Tok_Q_PRIVATE_PROPERTY)) { - expected_tok = Tok_Comma; - if (!skipTo(Tok_Comma)) - return false; - } - else if (!match(Tok_Q_PROPERTY) && - !match(Tok_Q_OVERRIDE) && - !match(Tok_QDOC_PROPERTY)) { - return false; - } - - if (!match(expected_tok)) - return false; - - QString name; - CodeChunk dataType; - if (!matchDataType(&dataType, &name)) - return false; - - PropertyNode *property = new PropertyNode(parent, name); - property->setAccess(Node::Public); - property->setLocation(location()); - property->setDataType(dataType.toString()); - - while (tok != Tok_RightParen && tok != Tok_Eoi) { - if (!match(Tok_Ident)) - return false; - QString key = previousLexeme(); - QString value; - - // Keywords with no associated values - if (key == "CONSTANT") { - property->setConstant(); - continue; - } - else if (key == "FINAL") { - property->setFinal(); - continue; - } - - if (match(Tok_Ident) || match(Tok_Number)) { - value = previousLexeme(); - } - else if (match(Tok_LeftParen)) { - int depth = 1; - while (tok != Tok_Eoi) { - if (tok == Tok_LeftParen) { - readToken(); - ++depth; - } else if (tok == Tok_RightParen) { - readToken(); - if (--depth == 0) - break; - } else { - readToken(); - } - } - value = "?"; - } - - if (key == "READ") - qdb_->addPropertyFunction(property, value, PropertyNode::Getter); - else if (key == "WRITE") { - qdb_->addPropertyFunction(property, value, PropertyNode::Setter); - property->setWritable(true); - } - else if (key == "STORED") - property->setStored(value.toLower() == "true"); - else if (key == "DESIGNABLE") { - QString v = value.toLower(); - if (v == "true") - property->setDesignable(true); - else if (v == "false") - property->setDesignable(false); - else { - property->setDesignable(false); - property->setRuntimeDesFunc(value); - } - } - else if (key == "RESET") - qdb_->addPropertyFunction(property, value, PropertyNode::Resetter); - else if (key == "NOTIFY") { - qdb_->addPropertyFunction(property, value, PropertyNode::Notifier); - } else if (key == "REVISION") { - int revision; - bool ok; - revision = value.toInt(&ok); - if (ok) - property->setRevision(revision); - else - location().warning(tr("Invalid revision number: %1").arg(value)); - } else if (key == "SCRIPTABLE") { - QString v = value.toLower(); - if (v == "true") - property->setScriptable(true); - else if (v == "false") - property->setScriptable(false); - else { - property->setScriptable(false); - property->setRuntimeScrFunc(value); - } - } - } - match(Tok_RightParen); - return true; -} - -/*! - Parse a C++ declaration. - */ -bool CppCodeParser::matchDeclList(Aggregate *parent) -{ - ExtraFuncData extra; - QString templateStuff; - int braceDepth0 = tokenizer->braceDepth(); - if (tok == Tok_RightBrace) // prevents failure on empty body - braceDepth0++; - - while (tokenizer->braceDepth() >= braceDepth0 && tok != Tok_Eoi) { - switch (tok) { - case Tok_Colon: - readToken(); - break; - case Tok_class: - case Tok_struct: - case Tok_union: - matchClassDecl(parent, templateStuff); - break; - case Tok_namespace: - matchNamespaceDecl(parent); - break; - case Tok_using: - matchUsingDecl(parent); - break; - case Tok_template: - { - CodeChunk dataType; - readToken(); - matchTemplateAngles(&dataType); - templateStuff = dataType.toString(); - } - continue; - case Tok_enum: - matchEnumDecl(parent); - break; - case Tok_typedef: - matchTypedefDecl(parent); - break; - case Tok_private: - readToken(); - access = Node::Private; - metaness_ = FunctionNode::Plain; - break; - case Tok_protected: - readToken(); - access = Node::Protected; - metaness_ = FunctionNode::Plain; - break; - case Tok_public: - readToken(); - access = Node::Public; - metaness_ = FunctionNode::Plain; - break; - case Tok_signals: - case Tok_Q_SIGNALS: - readToken(); - access = Node::Public; - metaness_ = FunctionNode::Signal; - break; - case Tok_slots: - case Tok_Q_SLOTS: - readToken(); - metaness_ = FunctionNode::Slot; - break; - case Tok_Q_OBJECT: - readToken(); - break; - case Tok_Q_OVERRIDE: - case Tok_Q_PROPERTY: - case Tok_Q_PRIVATE_PROPERTY: - case Tok_QDOC_PROPERTY: - if (!matchProperty(parent)) { - location().warning(tr("Failed to parse token %1 in property declaration").arg(lexeme())); - skipTo(Tok_RightParen); - match(Tok_RightParen); - } - break; - case Tok_Q_DECLARE_SEQUENTIAL_ITERATOR: - readToken(); - if (match(Tok_LeftParen) && match(Tok_Ident)) - sequentialIteratorClasses.insert(previousLexeme(), location().fileName()); - match(Tok_RightParen); - break; - case Tok_Q_DECLARE_MUTABLE_SEQUENTIAL_ITERATOR: - readToken(); - if (match(Tok_LeftParen) && match(Tok_Ident)) - mutableSequentialIteratorClasses.insert(previousLexeme(), location().fileName()); - match(Tok_RightParen); - break; - case Tok_Q_DECLARE_ASSOCIATIVE_ITERATOR: - readToken(); - if (match(Tok_LeftParen) && match(Tok_Ident)) - associativeIteratorClasses.insert(previousLexeme(), location().fileName()); - match(Tok_RightParen); - break; - case Tok_Q_DECLARE_MUTABLE_ASSOCIATIVE_ITERATOR: - readToken(); - if (match(Tok_LeftParen) && match(Tok_Ident)) - mutableAssociativeIteratorClasses.insert(previousLexeme(), location().fileName()); - match(Tok_RightParen); - break; - case Tok_Q_DECLARE_FLAGS: - readToken(); - if (match(Tok_LeftParen) && match(Tok_Ident)) { - QString flagsType = previousLexeme(); - if (match(Tok_Comma) && match(Tok_Ident)) { - QString name = previousLexeme(); - TypedefNode *flagsNode = new TypedefNode(parent, flagsType); - flagsNode->setAccess(access); - flagsNode->setLocation(location()); - EnumNode* en = static_cast<EnumNode*>(parent->findChildNode(name, Node::Enum)); - if (en) - en->setFlagsType(flagsNode); - } - } - match(Tok_RightParen); - break; - case Tok_QT_MODULE: - readToken(); - if (match(Tok_LeftParen) && match(Tok_Ident)) - physicalModuleName = previousLexeme(); - if (!physicalModuleName.startsWith("Qt")) - physicalModuleName.prepend("Qt"); - match(Tok_RightParen); - break; - default: - if (!matchFunctionDecl(parent, 0, 0, templateStuff, extra)) { - while (tok != Tok_Eoi && - (tokenizer->braceDepth() > braceDepth0 || - (!match(Tok_Semicolon) && - tok != Tok_public && tok != Tok_protected && - tok != Tok_private))) { - readToken(); - } - } - } - templateStuff.clear(); - } - return true; -} - -/*! - This is called by parseSourceFile() to do the actual parsing - and tree building. - */ -bool CppCodeParser::matchDocsAndStuff() -{ - ExtraFuncData extra; - const QSet<QString>& topicCommandsAllowed = topicCommands(); - const QSet<QString>& otherMetacommandsAllowed = otherMetaCommands(); - const QSet<QString>& metacommandsAllowed = topicCommandsAllowed + otherMetacommandsAllowed; - - while (tok != Tok_Eoi) { - if (tok == Tok_Doc) { - /* - lexeme() returns an entire qdoc comment. - */ - QString comment = lexeme(); - Location start_loc(location()); - readToken(); - - Doc::trimCStyleComment(start_loc,comment); - Location end_loc(location()); - - /* - Doc parses the comment. - */ - Doc doc(start_loc,end_loc,comment,metacommandsAllowed, topicCommandsAllowed); - QString topic; - bool isQmlPropertyTopic = false; - bool isJsPropertyTopic = false; - - const TopicList& topics = doc.topicsUsed(); - if (!topics.isEmpty()) { - topic = topics[0].topic; - if ((topic == COMMAND_QMLPROPERTY) || - (topic == COMMAND_QMLPROPERTYGROUP) || - (topic == COMMAND_QMLATTACHEDPROPERTY)) { - isQmlPropertyTopic = true; - } - else if ((topic == COMMAND_JSPROPERTY) || - (topic == COMMAND_JSPROPERTYGROUP) || - (topic == COMMAND_JSATTACHEDPROPERTY)) { - isJsPropertyTopic = true; - } - } - NodeList nodes; - DocList docs; - - if (topic.isEmpty()) { - QStringList parentPath; - FunctionNode *clone; - FunctionNode *func = 0; - - if (matchFunctionDecl(0, &parentPath, &clone, QString(), extra)) { - func = qdb_->findFunctionNode(parentPath, clone); - /* - If the node was not found, then search for it in the - open C++ namespaces. We don't expect this search to - be necessary often. Nor do we expect it to succeed - very often. - */ - if (func == 0) - func = qdb_->findNodeInOpenNamespace(parentPath, clone); - - if (func) { - func->borrowParameterNames(clone); - nodes.append(func); - docs.append(doc); - } - delete clone; - } - else { - doc.location().warning(tr("Cannot tie this documentation to anything"), - tr("I found a /*! ... */ comment, but there was no " - "topic command (e.g., '\\%1', '\\%2') in the " - "comment and no function definition following " - "the comment.") - .arg(COMMAND_FN).arg(COMMAND_PAGE)); - } - } - else if (isQmlPropertyTopic || isJsPropertyTopic) { - Doc nodeDoc = doc; - processQmlProperties(nodeDoc, nodes, docs, isJsPropertyTopic); - } - else { - ArgList args; - const QSet<QString>& topicCommandsUsed = topicCommandsAllowed & doc.metaCommandsUsed(); - if (topicCommandsUsed.count() > 0) { - topic = *topicCommandsUsed.constBegin(); - args = doc.metaCommandArgs(topic); - } - if (topicCommandsUsed.count() > 1) { - QString topics; - QSet<QString>::ConstIterator t = topicCommandsUsed.constBegin(); - while (t != topicCommandsUsed.constEnd()) { - topics += " \\" + *t + QLatin1Char(','); - ++t; - } - topics[topics.lastIndexOf(',')] = '.'; - int i = topics.lastIndexOf(','); - topics[i] = ' '; - topics.insert(i+1,"and"); - doc.location().warning(tr("Multiple topic commands found in comment: %1").arg(topics)); - } - ArgList::ConstIterator a = args.constBegin(); - while (a != args.constEnd()) { - Doc nodeDoc = doc; - Node *node = processTopicCommand(nodeDoc,topic,*a); - if (node != 0) { - nodes.append(node); - docs.append(nodeDoc); - } - ++a; - } - } - - NodeList::Iterator n = nodes.begin(); - QList<Doc>::Iterator d = docs.begin(); - while (n != nodes.end()) { - processOtherMetaCommands(*d, *n); - (*n)->setDoc(*d); - checkModuleInclusion(*n); - if ((*n)->isAggregate() && ((Aggregate *)*n)->includes().isEmpty()) { - Aggregate *m = static_cast<Aggregate *>(*n); - while (m->parent() && m->physicalModuleName().isEmpty()) { - m = m->parent(); - } - if (m == *n) - ((Aggregate *)*n)->addInclude((*n)->name()); - else - ((Aggregate *)*n)->setIncludes(m->includes()); - } - ++d; - ++n; - } - } - else if (tok == Tok_using) { - matchUsingDecl(0); - } - else { - QStringList parentPath; - FunctionNode *clone; - FunctionNode *node = 0; - - if (matchFunctionDecl(0, &parentPath, &clone, QString(), extra)) { - /* - The location of the definition is more interesting - than that of the declaration. People equipped with - a sophisticated text editor can respond to warnings - concerning undocumented functions very quickly. - - Signals are implemented in uninteresting files - generated by moc. - */ - node = qdb_->findFunctionNode(parentPath, clone); - if (node != 0 && node->metaness() != FunctionNode::Signal) - node->setLocation(clone->location()); - delete clone; - } - else { - if (tok != Tok_Doc) - readToken(); - } - } - } - return true; -} - -/*! - This function uses a Tokenizer to parse the function \a signature - in an attempt to match it to the signature of a child node of \a root. - If a match is found, \a funcPtr is set to point to the matching node - and true is returned. - */ -bool CppCodeParser::makeFunctionNode(const QString& signature, - QStringList* parentPathPtr, - FunctionNode** funcPtr, - ExtraFuncData& extra) -{ - Tokenizer* outerTokenizer = tokenizer; - int outerTok = tok; - - QByteArray latin1 = signature.toLatin1(); - Tokenizer stringTokenizer(location(), latin1); - stringTokenizer.setParsingFnOrMacro(true); - tokenizer = &stringTokenizer; - readToken(); - - inMacroCommand_ = extra.isMacro; - bool ok = matchFunctionDecl(extra.root, parentPathPtr, funcPtr, QString(), extra); - inMacroCommand_ = false; - // potential memory leak with funcPtr - - tokenizer = outerTokenizer; - tok = outerTok; - return ok; -} - -/*! - This function uses a Tokenizer to parse the \a parameters of a - function into the parameter vector \a {pvect}. - */ -bool CppCodeParser::parseParameters(const QString& parameters, - QVector<Parameter>& pvect, - bool& isQPrivateSignal) -{ - Tokenizer* outerTokenizer = tokenizer; - int outerTok = tok; - - QByteArray latin1 = parameters.toLatin1(); - Tokenizer stringTokenizer(Location(), latin1); - stringTokenizer.setParsingFnOrMacro(true); - tokenizer = &stringTokenizer; - readToken(); - - inMacroCommand_ = false; - do { - if (!matchParameter(pvect, isQPrivateSignal)) - return false; - } while (match(Tok_Comma)); - - tokenizer = outerTokenizer; - tok = outerTok; - return true; -} - -/*! - Create a new FunctionNode for a QML method or signal, as - specified by \a type, as a child of \a parent. \a sig is - the complete signature, and if \a attached is true, the - method or signal is "attached". \a qdoctag is the text of - the \a type. - - \a parent is the QML class node. The QML module and QML - type names have already been consumed to find \a parent. - What remains in \a sig is the method signature. The method - must be a child of \a parent. - */ -FunctionNode* CppCodeParser::makeFunctionNode(const Doc& doc, - const QString& sig, - Aggregate* parent, - Node::NodeType type, - bool attached, - QString qdoctag) -{ - QStringList pp; - FunctionNode* fn = 0; - ExtraFuncData extra(parent, type, attached); - if (!makeFunctionNode(sig, &pp, &fn, extra) && !makeFunctionNode("void " + sig, &pp, &fn, extra)) { - doc.location().warning(tr("Invalid syntax in '\\%1'").arg(qdoctag)); - } - return fn; -} - -void CppCodeParser::parseQiteratorDotH(const Location &location, const QString &filePath) -{ - QFile file(filePath); - if (!file.open(QFile::ReadOnly)) - return; - - QString text = file.readAll(); - text.remove("\r"); - text.remove("\\\n"); - QStringList lines = text.split(QLatin1Char('\n')); - lines = lines.filter("Q_DECLARE"); - lines.replaceInStrings(QRegExp("#define Q[A-Z_]*\\(C\\)"), QString()); - - if (lines.size() == 4) { - sequentialIteratorDefinition = lines[0]; - mutableSequentialIteratorDefinition = lines[1]; - associativeIteratorDefinition = lines[2]; - mutableAssociativeIteratorDefinition = lines[3]; - } - else { - location.warning(tr("The qiterator.h hack failed")); - } -} - -void CppCodeParser::instantiateIteratorMacro(const QString &container, - const QString &includeFile, - const QString ¯oDef) -{ - QString resultingCode = macroDef; - resultingCode.replace(QRegExp("\\bC\\b"), container); - resultingCode.remove(QRegExp("\\s*##\\s*")); - - Location loc(includeFile); // hack to get the include file for free - QByteArray latin1 = resultingCode.toLatin1(); - Tokenizer stringTokenizer(loc, latin1); - tokenizer = &stringTokenizer; - readToken(); - matchDeclList(QDocDatabase::qdocDB()->primaryTreeRoot()); -} - -void CppCodeParser::createExampleFileNodes(DocumentNode *dn) -{ - QString examplePath = dn->name(); - QString proFileName = examplePath + QLatin1Char('/') + examplePath.split(QLatin1Char('/')).last() + ".pro"; - QString userFriendlyFilePath; - - QString fullPath = Config::findFile(dn->doc().location(), - exampleFiles, - exampleDirs, - proFileName, - userFriendlyFilePath); - - if (fullPath.isEmpty()) { - QString tmp = proFileName; - proFileName = examplePath + QLatin1Char('/') + "qbuild.pro"; - userFriendlyFilePath.clear(); - fullPath = Config::findFile(dn->doc().location(), - exampleFiles, - exampleDirs, - proFileName, - userFriendlyFilePath); - if (fullPath.isEmpty()) { - proFileName = examplePath + QLatin1Char('/') + examplePath.split(QLatin1Char('/')).last() + ".qmlproject"; - userFriendlyFilePath.clear(); - fullPath = Config::findFile(dn->doc().location(), - exampleFiles, - exampleDirs, - proFileName, - userFriendlyFilePath); - if (fullPath.isEmpty()) { - QString details = QLatin1String("Example directories: ") + exampleDirs.join(QLatin1Char(' ')); - if (!exampleFiles.isEmpty()) - details += QLatin1String(", example files: ") + exampleFiles.join(QLatin1Char(' ')); - dn->location().warning(tr("Cannot find file '%1' or '%2'").arg(tmp).arg(proFileName), details); - dn->location().warning(tr(" EXAMPLE PATH DOES NOT EXIST: %1").arg(examplePath), details); - return; - } - } - } - - int sizeOfBoringPartOfName = fullPath.size() - proFileName.size(); - if (fullPath.startsWith("./")) - sizeOfBoringPartOfName = sizeOfBoringPartOfName - 2; - fullPath.truncate(fullPath.lastIndexOf('/')); - - QStringList exampleFiles = Config::getFilesHere(fullPath,exampleNameFilter); - QString imagesPath = fullPath + "/images"; - QStringList imageFiles = Config::getFilesHere(imagesPath,exampleImageFilter); - if (!exampleFiles.isEmpty()) { - // move main.cpp and to the end, if it exists - QString mainCpp; - QMutableStringListIterator i(exampleFiles); - i.toBack(); - while (i.hasPrevious()) { - QString fileName = i.previous(); - if (fileName.endsWith("/main.cpp")) { - mainCpp = fileName; - i.remove(); - } - else if (fileName.contains("/qrc_") || fileName.contains("/moc_") - || fileName.contains("/ui_")) - i.remove(); - } - if (!mainCpp.isEmpty()) - exampleFiles.append(mainCpp); - - // add any qmake Qt resource files and qmake project files - exampleFiles += Config::getFilesHere(fullPath, "*.qrc *.pro *.qmlproject qmldir"); - } - - foreach (const QString &exampleFile, exampleFiles) { - new DocumentNode(dn, - exampleFile.mid(sizeOfBoringPartOfName), - Node::File, - Node::NoPageType); - } - foreach (const QString &imageFile, imageFiles) { - new DocumentNode(dn, - imageFile.mid(sizeOfBoringPartOfName), - Node::Image, - Node::NoPageType); - } -} - -QT_END_NAMESPACE diff --git a/src/tools/qdoc/cppcodeparser.h b/src/tools/qdoc/cppcodeparser.h deleted file mode 100644 index ec04482321..0000000000 --- a/src/tools/qdoc/cppcodeparser.h +++ /dev/null @@ -1,255 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#ifndef CPPCODEPARSER_H -#define CPPCODEPARSER_H - -#include <qregexp.h> - -#include "codeparser.h" - -QT_BEGIN_NAMESPACE - -class ClassNode; -class CodeChunk; -class CppCodeParserPrivate; -class FunctionNode; -class Aggregate; -class Tokenizer; - -class CppCodeParser : public CodeParser -{ - Q_DECLARE_TR_FUNCTIONS(QDoc::CppCodeParser) - - struct ExtraFuncData { - Aggregate* root; // Used as the parent. - Node::NodeType type; // The node type: Function, etc. - bool isAttached; // If true, the method is attached. - bool isMacro; // If true, we are parsing a macro signature. - ExtraFuncData() : root(0), type(Node::Function), isAttached(false), isMacro(false) { } - ExtraFuncData(Aggregate* r, Node::NodeType t, bool a) - : root(r), type(t), isAttached(a), isMacro(false) { } - }; - -public: - CppCodeParser(); - ~CppCodeParser(); - static CppCodeParser* cppParser() { return cppParser_; } - - virtual void initializeParser(const Config& config) Q_DECL_OVERRIDE; - virtual void terminateParser() Q_DECL_OVERRIDE; - virtual QString language() Q_DECL_OVERRIDE; - virtual QStringList headerFileNameFilter() Q_DECL_OVERRIDE; - virtual QStringList sourceFileNameFilter() Q_DECL_OVERRIDE; - virtual void parseHeaderFile(const Location& location, const QString& filePath) Q_DECL_OVERRIDE; - virtual void parseSourceFile(const Location& location, const QString& filePath) Q_DECL_OVERRIDE; - virtual void doneParsingHeaderFiles() Q_DECL_OVERRIDE; - virtual void doneParsingSourceFiles() Q_DECL_OVERRIDE; - bool parseParameters(const QString& parameters, QVector<Parameter>& pvect, bool& isQPrivateSignal); - -protected: - const QSet<QString>& topicCommands(); - const QSet<QString>& otherMetaCommands(); - virtual Node* processTopicCommand(const Doc& doc, - const QString& command, - const ArgLocPair& arg); - void processQmlProperties(const Doc& doc, NodeList& nodes, DocList& docs, bool jsProps); - bool splitQmlPropertyGroupArg(const QString& arg, - QString& module, - QString& element, - QString& name); - bool splitQmlPropertyArg(const QString& arg, - QString& type, - QString& module, - QString& element, - QString& name); - bool splitQmlMethodArg(const QString& arg, - QString& type, - QString& module, - QString& element); - virtual void processOtherMetaCommand(const Doc& doc, - const QString& command, - const ArgLocPair& argLocPair, - Node *node); - void processOtherMetaCommands(const Doc& doc, Node *node); - - protected: - void reset(); - void readToken(); - const Location& location(); - QString previousLexeme(); - QString lexeme(); - - private: - bool match(int target); - bool skipTo(int target); - bool matchCompat(); - bool matchModuleQualifier(QString& name); - bool matchTemplateAngles(CodeChunk *type = 0); - bool matchTemplateHeader(); - bool matchDataType(CodeChunk *type, QString *var = 0); - bool matchParameter(QVector<Parameter>& pvect, bool& isQPrivateSignal); - bool matchFunctionDecl(Aggregate *parent, - QStringList *parentPathPtr, - FunctionNode **funcPtr, - const QString &templateStuff, - ExtraFuncData& extra); - bool matchBaseSpecifier(ClassNode *classe, bool isClass); - bool matchBaseList(ClassNode *classe, bool isClass); - bool matchClassDecl(Aggregate *parent, - const QString &templateStuff = QString()); - bool matchNamespaceDecl(Aggregate *parent); - bool matchUsingDecl(Aggregate* parent); - bool matchEnumItem(Aggregate *parent, EnumNode *enume); - bool matchEnumDecl(Aggregate *parent); - bool matchTypedefDecl(Aggregate *parent); - bool matchProperty(Aggregate *parent); - bool matchDeclList(Aggregate *parent); - bool matchDocsAndStuff(); - bool makeFunctionNode(const QString &synopsis, - QStringList *parentPathPtr, - FunctionNode **funcPtr, - ExtraFuncData& params); - FunctionNode* makeFunctionNode(const Doc& doc, - const QString& sig, - Aggregate* parent, - Node::NodeType type, - bool attached, - QString qdoctag); - void parseQiteratorDotH(const Location &location, const QString &filePath); - void instantiateIteratorMacro(const QString &container, - const QString &includeFile, - const QString ¯oDef); - void createExampleFileNodes(DocumentNode *dn); - int matchFunctionModifier(); - - protected: - QMap<QString, Node::NodeType> nodeTypeMap; - Tokenizer *tokenizer; - int tok; - Node::Access access; - FunctionNode::Metaness metaness_; - QString physicalModuleName; - QStringList lastPath_; - QRegExp varComment; - QRegExp sep; - - private: - QString sequentialIteratorDefinition; - QString mutableSequentialIteratorDefinition; - QString associativeIteratorDefinition; - QString mutableAssociativeIteratorDefinition; - QMap<QString, QString> sequentialIteratorClasses; - QMap<QString, QString> mutableSequentialIteratorClasses; - QMap<QString, QString> associativeIteratorClasses; - QMap<QString, QString> mutableAssociativeIteratorClasses; - - static QStringList exampleFiles; - static QStringList exampleDirs; - static CppCodeParser* cppParser_; - QString exampleNameFilter; - QString exampleImageFilter; -}; - -#define COMMAND_ABSTRACT Doc::alias("abstract") -#define COMMAND_CLASS Doc::alias("class") -#define COMMAND_CONTENTSPAGE Doc::alias("contentspage") -#define COMMAND_DITAMAP Doc::alias("ditamap") -#define COMMAND_ENUM Doc::alias("enum") -#define COMMAND_EXAMPLE Doc::alias("example") -#define COMMAND_EXTERNALPAGE Doc::alias("externalpage") -#define COMMAND_FILE Doc::alias("file") -#define COMMAND_FN Doc::alias("fn") -#define COMMAND_GROUP Doc::alias("group") -#define COMMAND_HEADERFILE Doc::alias("headerfile") -#define COMMAND_INDEXPAGE Doc::alias("indexpage") -#define COMMAND_INHEADERFILE Doc::alias("inheaderfile") -#define COMMAND_MACRO Doc::alias("macro") -#define COMMAND_MODULE Doc::alias("module") -#define COMMAND_NAMESPACE Doc::alias("namespace") -#define COMMAND_OVERLOAD Doc::alias("overload") -#define COMMAND_NEXTPAGE Doc::alias("nextpage") -#define COMMAND_PAGE Doc::alias("page") -#define COMMAND_PREVIOUSPAGE Doc::alias("previouspage") -#define COMMAND_PROPERTY Doc::alias("property") -#define COMMAND_REIMP Doc::alias("reimp") -#define COMMAND_RELATES Doc::alias("relates") -#define COMMAND_STARTPAGE Doc::alias("startpage") -#define COMMAND_TYPEDEF Doc::alias("typedef") -#define COMMAND_VARIABLE Doc::alias("variable") -#define COMMAND_QMLABSTRACT Doc::alias("qmlabstract") -#define COMMAND_QMLTYPE Doc::alias("qmltype") -#define COMMAND_QMLPROPERTY Doc::alias("qmlproperty") -#define COMMAND_QMLPROPERTYGROUP Doc::alias("qmlpropertygroup") -#define COMMAND_QMLATTACHEDPROPERTY Doc::alias("qmlattachedproperty") -#define COMMAND_QMLINHERITS Doc::alias("inherits") -#define COMMAND_QMLINSTANTIATES Doc::alias("instantiates") -#define COMMAND_QMLSIGNAL Doc::alias("qmlsignal") -#define COMMAND_QMLATTACHEDSIGNAL Doc::alias("qmlattachedsignal") -#define COMMAND_QMLMETHOD Doc::alias("qmlmethod") -#define COMMAND_QMLATTACHEDMETHOD Doc::alias("qmlattachedmethod") -#define COMMAND_QMLDEFAULT Doc::alias("default") -#define COMMAND_QMLREADONLY Doc::alias("readonly") -#define COMMAND_QMLBASICTYPE Doc::alias("qmlbasictype") -#define COMMAND_QMLMODULE Doc::alias("qmlmodule") -#define COMMAND_AUDIENCE Doc::alias("audience") -#define COMMAND_CATEGORY Doc::alias("category") -#define COMMAND_PRODNAME Doc::alias("prodname") -#define COMMAND_COMPONENT Doc::alias("component") -#define COMMAND_AUTHOR Doc::alias("author") -#define COMMAND_PUBLISHER Doc::alias("publisher") -#define COMMAND_COPYRYEAR Doc::alias("copyryear") -#define COMMAND_COPYRHOLDER Doc::alias("copyrholder") -#define COMMAND_PERMISSIONS Doc::alias("permissions") -#define COMMAND_LIFECYCLEVERSION Doc::alias("lifecycleversion") -#define COMMAND_LIFECYCLEWSTATUS Doc::alias("lifecyclestatus") -#define COMMAND_LICENSEYEAR Doc::alias("licenseyear") -#define COMMAND_LICENSENAME Doc::alias("licensename") -#define COMMAND_LICENSEDESCRIPTION Doc::alias("licensedescription") -#define COMMAND_RELEASEDATE Doc::alias("releasedate") -#define COMMAND_QTVARIABLE Doc::alias("qtvariable") -// Some of these are not used currenmtly, but they are included now for completeness. -#define COMMAND_JSTYPE Doc::alias("jstype") -#define COMMAND_JSPROPERTY Doc::alias("jsproperty") -#define COMMAND_JSPROPERTYGROUP Doc::alias("jspropertygroup") -#define COMMAND_JSATTACHEDPROPERTY Doc::alias("jsattachedproperty") -#define COMMAND_JSSIGNAL Doc::alias("jssignal") -#define COMMAND_JSATTACHEDSIGNAL Doc::alias("jsattachedsignal") -#define COMMAND_JSMETHOD Doc::alias("jsmethod") -#define COMMAND_JSATTACHEDMETHOD Doc::alias("jsattachedmethod") -#define COMMAND_JSBASICTYPE Doc::alias("jsbasictype") -#define COMMAND_JSMODULE Doc::alias("jsmodule") - -QT_END_NAMESPACE - -#endif diff --git a/src/tools/qdoc/doc.cpp b/src/tools/qdoc/doc.cpp deleted file mode 100644 index 4ed5894543..0000000000 --- a/src/tools/qdoc/doc.cpp +++ /dev/null @@ -1,3380 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include "config.h" -#include "doc.h" -#include "codemarker.h" -#include "editdistance.h" -#include "openedlist.h" -#include "quoter.h" -#include "text.h" -#include "atom.h" -#include "tokenizer.h" -#include <qdatetime.h> -#include <qfile.h> -#include <qfileinfo.h> -#include <qhash.h> -#include <qtextstream.h> -#include <qregexp.h> -#include <ctype.h> -#include <limits.h> -#include <qdebug.h> -#include "generator.h" - -QT_BEGIN_NAMESPACE - -Q_GLOBAL_STATIC(QSet<QString>, null_Set_QString) -Q_GLOBAL_STATIC(TopicList, nullTopicList) -Q_GLOBAL_STATIC(QStringList, null_QStringList) -Q_GLOBAL_STATIC(QList<Text>, null_QList_Text) -Q_GLOBAL_STATIC(QStringMultiMap, null_QStringMultiMap) - -struct Macro -{ - QString defaultDef; - Location defaultDefLocation; - QStringMap otherDefs; - int numParams; -}; - -enum { - CMD_A, - CMD_ANNOTATEDLIST, - CMD_B, - CMD_BADCODE, - CMD_BOLD, - CMD_BR, - CMD_BRIEF, - CMD_C, - CMD_CAPTION, - CMD_CHAPTER, - CMD_CODE, - CMD_CODELINE, - CMD_DIV, - CMD_DOTS, - CMD_E, - CMD_ELSE, - CMD_ENDCHAPTER, - CMD_ENDCODE, - CMD_ENDDIV, - CMD_ENDFOOTNOTE, - CMD_ENDIF, - CMD_ENDLEGALESE, - CMD_ENDLINK, - CMD_ENDLIST, - CMD_ENDMAPREF, - CMD_ENDOMIT, - CMD_ENDPART, - CMD_ENDQUOTATION, - CMD_ENDRAW, - CMD_ENDSECTION1, - CMD_ENDSECTION2, - CMD_ENDSECTION3, - CMD_ENDSECTION4, - CMD_ENDSIDEBAR, - CMD_ENDTABLE, - CMD_ENDTOPICREF, - CMD_FOOTNOTE, - CMD_GENERATELIST, - CMD_GRANULARITY, - CMD_HEADER, - CMD_HR, - CMD_I, - CMD_IF, - CMD_IMAGE, - CMD_IMPORTANT, - CMD_INCLUDE, - CMD_INLINEIMAGE, - CMD_INDEX, - CMD_INPUT, - CMD_KEYWORD, - CMD_L, - CMD_LEGALESE, - CMD_LI, - CMD_LINK, - CMD_LIST, - CMD_MAPREF, - CMD_META, - CMD_NEWCODE, - CMD_NOTE, - CMD_O, - CMD_OLDCODE, - CMD_OMIT, - CMD_OMITVALUE, - CMD_OVERLOAD, - CMD_PART, - CMD_PRINTLINE, - CMD_PRINTTO, - CMD_PRINTUNTIL, - CMD_QUOTATION, - CMD_QUOTEFILE, - CMD_QUOTEFROMFILE, - CMD_QUOTEFUNCTION, - CMD_RAW, - CMD_ROW, - CMD_SA, - CMD_SECTION1, - CMD_SECTION2, - CMD_SECTION3, - CMD_SECTION4, - CMD_SIDEBAR, - CMD_SINCELIST, - CMD_SKIPLINE, - CMD_SKIPTO, - CMD_SKIPUNTIL, - CMD_SNIPPET, - CMD_SPAN, - CMD_SUB, - CMD_SUP, - CMD_TABLE, - CMD_TABLEOFCONTENTS, - CMD_TARGET, - CMD_TOPICREF, - CMD_TT, - CMD_UICONTROL, - CMD_UNDERLINE, - CMD_UNICODE, - CMD_VALUE, - CMD_WARNING, - CMD_QML, - CMD_ENDQML, - CMD_CPP, - CMD_ENDCPP, - CMD_QMLTEXT, - CMD_ENDQMLTEXT, - CMD_CPPTEXT, - CMD_ENDCPPTEXT, - CMD_JS, - CMD_ENDJS, - NOT_A_CMD -}; - -static struct { - const char *english; - int no; - QString *alias; -} cmds[] = { - { "a", CMD_A, 0 }, - { "annotatedlist", CMD_ANNOTATEDLIST, 0 }, - { "b", CMD_B, 0 }, - { "badcode", CMD_BADCODE, 0 }, - { "bold", CMD_BOLD, 0 }, - { "br", CMD_BR, 0 }, - { "brief", CMD_BRIEF, 0 }, - { "c", CMD_C, 0 }, - { "caption", CMD_CAPTION, 0 }, - { "chapter", CMD_CHAPTER, 0 }, - { "code", CMD_CODE, 0 }, - { "codeline", CMD_CODELINE, 0}, - { "div", CMD_DIV, 0 }, - { "dots", CMD_DOTS, 0 }, - { "e", CMD_E, 0 }, - { "else", CMD_ELSE, 0 }, - { "endchapter", CMD_ENDCHAPTER, 0 }, - { "endcode", CMD_ENDCODE, 0 }, - { "enddiv", CMD_ENDDIV, 0 }, - { "endfootnote", CMD_ENDFOOTNOTE, 0 }, - { "endif", CMD_ENDIF, 0 }, - { "endlegalese", CMD_ENDLEGALESE, 0 }, - { "endlink", CMD_ENDLINK, 0 }, - { "endlist", CMD_ENDLIST, 0 }, - { "endmapref", CMD_ENDMAPREF, 0 }, - { "endomit", CMD_ENDOMIT, 0 }, - { "endpart", CMD_ENDPART, 0 }, - { "endquotation", CMD_ENDQUOTATION, 0 }, - { "endraw", CMD_ENDRAW, 0 }, - { "endsection1", CMD_ENDSECTION1, 0 }, // ### don't document for now - { "endsection2", CMD_ENDSECTION2, 0 }, // ### don't document for now - { "endsection3", CMD_ENDSECTION3, 0 }, // ### don't document for now - { "endsection4", CMD_ENDSECTION4, 0 }, // ### don't document for now - { "endsidebar", CMD_ENDSIDEBAR, 0 }, - { "endtable", CMD_ENDTABLE, 0 }, - { "endtopicref", CMD_ENDTOPICREF, 0 }, - { "footnote", CMD_FOOTNOTE, 0 }, - { "generatelist", CMD_GENERATELIST, 0 }, - { "granularity", CMD_GRANULARITY, 0 }, // ### don't document for now - { "header", CMD_HEADER, 0 }, - { "hr", CMD_HR, 0 }, - { "i", CMD_I, 0 }, - { "if", CMD_IF, 0 }, - { "image", CMD_IMAGE, 0 }, - { "important", CMD_IMPORTANT, 0 }, - { "include", CMD_INCLUDE, 0 }, - { "inlineimage", CMD_INLINEIMAGE, 0 }, - { "index", CMD_INDEX, 0 }, // ### don't document for now - { "input", CMD_INPUT, 0 }, - { "keyword", CMD_KEYWORD, 0 }, - { "l", CMD_L, 0 }, - { "legalese", CMD_LEGALESE, 0 }, - { "li", CMD_LI, 0 }, - { "link", CMD_LINK, 0 }, - { "list", CMD_LIST, 0 }, - { "mapref", CMD_MAPREF, 0 }, - { "meta", CMD_META, 0 }, - { "newcode", CMD_NEWCODE, 0 }, - { "note", CMD_NOTE, 0 }, - { "o", CMD_O, 0 }, - { "oldcode", CMD_OLDCODE, 0 }, - { "omit", CMD_OMIT, 0 }, - { "omitvalue", CMD_OMITVALUE, 0 }, - { "overload", CMD_OVERLOAD, 0 }, - { "part", CMD_PART, 0 }, - { "printline", CMD_PRINTLINE, 0 }, - { "printto", CMD_PRINTTO, 0 }, - { "printuntil", CMD_PRINTUNTIL, 0 }, - { "quotation", CMD_QUOTATION, 0 }, - { "quotefile", CMD_QUOTEFILE, 0 }, - { "quotefromfile", CMD_QUOTEFROMFILE, 0 }, - { "quotefunction", CMD_QUOTEFUNCTION, 0 }, - { "raw", CMD_RAW, 0 }, - { "row", CMD_ROW, 0 }, - { "sa", CMD_SA, 0 }, - { "section1", CMD_SECTION1, 0 }, - { "section2", CMD_SECTION2, 0 }, - { "section3", CMD_SECTION3, 0 }, - { "section4", CMD_SECTION4, 0 }, - { "sidebar", CMD_SIDEBAR, 0 }, - { "sincelist", CMD_SINCELIST, 0 }, - { "skipline", CMD_SKIPLINE, 0 }, - { "skipto", CMD_SKIPTO, 0 }, - { "skipuntil", CMD_SKIPUNTIL, 0 }, - { "snippet", CMD_SNIPPET, 0 }, - { "span", CMD_SPAN, 0 }, - { "sub", CMD_SUB, 0 }, - { "sup", CMD_SUP, 0 }, - { "table", CMD_TABLE, 0 }, - { "tableofcontents", CMD_TABLEOFCONTENTS, 0 }, - { "target", CMD_TARGET, 0 }, - { "topicref", CMD_TOPICREF, 0 }, - { "tt", CMD_TT, 0 }, - { "uicontrol", CMD_UICONTROL, 0 }, - { "underline", CMD_UNDERLINE, 0 }, - { "unicode", CMD_UNICODE, 0 }, - { "value", CMD_VALUE, 0 }, - { "warning", CMD_WARNING, 0 }, - { "qml", CMD_QML, 0 }, - { "endqml", CMD_ENDQML, 0 }, - { "cpp", CMD_CPP, 0 }, - { "endcpp", CMD_ENDCPP, 0 }, - { "qmltext", CMD_QMLTEXT, 0 }, - { "endqmltext", CMD_ENDQMLTEXT, 0 }, - { "cpptext", CMD_CPPTEXT, 0 }, - { "endcpptext", CMD_ENDCPPTEXT, 0 }, - { "js", CMD_JS, 0 }, - { "endjs", CMD_ENDJS, 0 }, - { 0, 0, 0 } -}; - -typedef QHash<QString, int> QHash_QString_int; -typedef QHash<QString, Macro> QHash_QString_Macro; - -Q_GLOBAL_STATIC(QStringMap, aliasMap) -Q_GLOBAL_STATIC(QHash_QString_int, cmdHash) -Q_GLOBAL_STATIC(QHash_QString_Macro, macroHash) - -class DocPrivateExtra -{ -public: - Doc::Sections granularity_; - Doc::Sections section_; // ### - QList<Atom*> tableOfContents_; - QVector<int> tableOfContentsLevels_; - QList<Atom*> keywords_; - QList<Atom*> targets_; - QStringMultiMap metaMap_; - - DocPrivateExtra() - : granularity_(Doc::Part) - , section_(Doc::NoSection) - { } -}; - -struct Shared // ### get rid of -{ - Shared() - : count(1) { } - void ref() { ++count; } - bool deref() { return (--count == 0); } - - int count; -}; - -static QString cleanLink(const QString &link) -{ - int colonPos = link.indexOf(':'); - if ((colonPos == -1) || - (!link.startsWith("file:") && !link.startsWith("mailto:"))) - return link; - return link.mid(colonPos + 1).simplified(); -} - -typedef QMap<QString, ArgList> CommandMap; - -class DocPrivate : public Shared -{ -public: - DocPrivate(const Location& start = Location::null, - const Location& end = Location::null, - const QString& source = QString()); - ~DocPrivate(); - - void addAlso(const Text& also); - void constructExtra(); - bool isEnumDocSimplifiable() const; - - // ### move some of this in DocPrivateExtra - Location start_loc; - Location end_loc; - QString src; - Text text; - QSet<QString> params; - QList<Text> alsoList; - QStringList enumItemList; - QStringList omitEnumItemList; - QSet<QString> metacommandsUsed; - CommandMap metaCommandMap; - bool hasLegalese : 1; - bool hasSectioningUnits : 1; - DocPrivateExtra *extra; - TopicList topics_; - DitaRefList ditamap_; -}; - -DocPrivate::DocPrivate(const Location& start, - const Location& end, - const QString& source) - : start_loc(start), - end_loc(end), - src(source), - hasLegalese(false), - hasSectioningUnits(false), - extra(0) -{ - // nothing. -} - -/*! - If the doc is a ditamap, the destructor deletes each element - in the ditamap structure. These were allocated as needed. - */ -DocPrivate::~DocPrivate() -{ - delete extra; - foreach (DitaRef* t, ditamap_) { - delete t; - } -} - -void DocPrivate::addAlso(const Text& also) -{ - alsoList.append(also); -} - -void DocPrivate::constructExtra() -{ - if (extra == 0) - extra = new DocPrivateExtra; -} - -bool DocPrivate::isEnumDocSimplifiable() const -{ - bool justMetColon = false; - int numValueTables = 0; - - const Atom *atom = text.firstAtom(); - while (atom) { - if (atom->type() == Atom::AutoLink || atom->type() == Atom::String) { - justMetColon = atom->string().endsWith(QLatin1Char(':')); - } - else if ((atom->type() == Atom::ListLeft) && - (atom->string() == ATOM_LIST_VALUE)) { - if (justMetColon || numValueTables > 0) - return false; - ++numValueTables; - } - atom = atom->next(); - } - return true; -} - -class DocParser -{ - Q_DECLARE_TR_FUNCTIONS(QDoc::DocParser) - -public: - void parse(const QString &source, - DocPrivate *docPrivate, - const QSet<QString> &metaCommandSet, - const QSet<QString>& possibleTopics); - - static int endCmdFor(int cmd); - static QString cmdName(int cmd); - static QString endCmdName(int cmd); - static QString untabifyEtc(const QString& str); - static int indentLevel(const QString& str); - static QString unindent(int level, const QString& str); - static QString slashed(const QString& str); - - static int tabSize; - static QStringList exampleFiles; - static QStringList exampleDirs; - static QStringList sourceFiles; - static QStringList sourceDirs; - static bool quoting; - -private: - Location& location(); - QString detailsUnknownCommand(const QSet<QString>& metaCommandSet, - const QString& str); - void insertTarget(const QString& target, bool keyword); - void include(const QString& fileName, const QString& identifier); - void startFormat(const QString& format, int cmd); - bool openCommand(int cmd); - bool closeCommand(int endCmd); - void startSection(Doc::Sections unit, int cmd); - void endSection(int unit, int endCmd); - void parseAlso(); - void append(const QString &string); - void append(Atom::AtomType type, const QString& string = QString()); - void append(Atom::AtomType type, const QString& p1, const QString& p2); - void append(const QString& p1, const QString& p2); - void appendChar(QChar ch); - void appendWord(const QString &word); - void appendToCode(const QString &code); - void appendToCode(const QString &code, Atom::AtomType defaultType); - void startNewPara(); - void enterPara(Atom::AtomType leftType = Atom::ParaLeft, - Atom::AtomType rightType = Atom::ParaRight, - const QString& string = QString()); - void leavePara(); - void leaveValue(); - void leaveValueList(); - void leaveTableRow(); - CodeMarker *quoteFromFile(); - void expandMacro(const QString& name, const QString& def, int numParams); - QString expandMacroToString(const QString &name, const QString &def, int numParams); - Doc::Sections getSectioningUnit(); - QString getArgument(bool verbatim = false); - QString getBracedArgument(bool verbatim); - QString getBracketedArgument(); - QString getOptionalArgument(); - QString getRestOfLine(); - QString getMetaCommandArgument(const QString &cmdStr); - QString getUntilEnd(int cmd); - QString getCode(int cmd, CodeMarker *marker); - QString getUnmarkedCode(int cmd); - - bool isBlankLine(); - bool isLeftBraceAhead(); - bool isLeftBracketAhead(); - void skipSpacesOnLine(); - void skipSpacesOrOneEndl(); - void skipAllSpaces(); - void skipToNextPreprocessorCommand(); - - QStack<int> openedInputs; - - QString in; - int pos; - int len; - Location cachedLoc; - int cachedPos; - - DocPrivate* priv; - enum ParagraphState { - OutsideParagraph, - InSingleLineParagraph, - InMultiLineParagraph - }; - ParagraphState paraState; - bool inTableHeader; - bool inTableRow; - bool inTableItem; - bool indexStartedPara; // ### rename - Atom::AtomType pendingParaLeftType; - Atom::AtomType pendingParaRightType; - QString pendingParaString; - - int braceDepth; - int minIndent; - Doc::Sections currentSection; - QMap<QString, Location> targetMap_; - QMap<int, QString> pendingFormats; - QStack<int> openedCommands; - QStack<OpenedList> openedLists; - Quoter quoter; - QStack<DitaRef*> ditarefs_; -}; - -int DocParser::tabSize; -QStringList DocParser::exampleFiles; -QStringList DocParser::exampleDirs; -QStringList DocParser::sourceFiles; -QStringList DocParser::sourceDirs; -bool DocParser::quoting; - -/*! - Parse the \a source string to build a Text data structure - in \a docPrivate. The Text data structure is a linked list - of Atoms. - - \a metaCommandSet is the set of metacommands that may be - found in \a source. These metacommands are not markup text - commands. They are topic commands and related metacommands. - */ -void DocParser::parse(const QString& source, - DocPrivate *docPrivate, - const QSet<QString>& metaCommandSet, - const QSet<QString>& possibleTopics) -{ - in = source; - pos = 0; - len = in.length(); - cachedLoc = docPrivate->start_loc; - cachedPos = 0; - priv = docPrivate; - priv->text << Atom::Nop; - priv->topics_.clear(); - - paraState = OutsideParagraph; - inTableHeader = false; - inTableRow = false; - inTableItem = false; - indexStartedPara = false; - pendingParaLeftType = Atom::Nop; - pendingParaRightType = Atom::Nop; - - braceDepth = 0; - minIndent = INT_MAX; - currentSection = Doc::NoSection; - openedCommands.push(CMD_OMIT); - quoter.reset(); - - CodeMarker *marker = 0; - Atom *currentLinkAtom = 0; - QString p1, p2; - QStack<bool> preprocessorSkipping; - int numPreprocessorSkipping = 0; - - while (pos < len) { - QChar ch = in.at(pos); - - switch (ch.unicode()) { - case '\\': - { - QString cmdStr; - pos++; - while (pos < len) { - ch = in.at(pos); - if (ch.isLetterOrNumber()) { - cmdStr += ch; - pos++; - } - else { - break; - } - } - if (cmdStr.isEmpty()) { - if (pos < len) { - enterPara(); - if (in.at(pos).isSpace()) { - skipAllSpaces(); - appendChar(QLatin1Char(' ')); - } - else { - appendChar(in.at(pos++)); - } - } - } - else { - int cmd = cmdHash()->value(cmdStr,NOT_A_CMD); - switch (cmd) { - case CMD_A: - enterPara(); - p1 = getArgument(); - append(Atom::FormattingLeft,ATOM_FORMATTING_PARAMETER); - append(Atom::String, p1); - append(Atom::FormattingRight,ATOM_FORMATTING_PARAMETER); - priv->params.insert(p1); - break; - case CMD_BADCODE: - leavePara(); - append(Atom::CodeBad,getCode(CMD_BADCODE, marker)); - break; - case CMD_BR: - enterPara(); - append(Atom::BR); - break; - case CMD_BOLD: - location().warning(tr("'\\bold' is deprecated. Use '\\b'")); - case CMD_B: - startFormat(ATOM_FORMATTING_BOLD, cmd); - break; - case CMD_BRIEF: - leavePara(); - enterPara(Atom::BriefLeft, Atom::BriefRight); - break; - case CMD_C: - enterPara(); - p1 = untabifyEtc(getArgument(true)); - marker = CodeMarker::markerForCode(p1); - append(Atom::C, marker->markedUpCode(p1, 0, location())); - break; - case CMD_CAPTION: - leavePara(); - enterPara(Atom::CaptionLeft, Atom::CaptionRight); - break; - case CMD_CHAPTER: - startSection(Doc::Chapter, cmd); - break; - case CMD_CODE: - leavePara(); - append(Atom::Code, getCode(CMD_CODE, 0)); - break; - case CMD_QML: - leavePara(); - append(Atom::Qml, getCode(CMD_QML, CodeMarker::markerForLanguage(QLatin1String("QML")))); - break; - case CMD_QMLTEXT: - append(Atom::QmlText); - break; - case CMD_JS: - leavePara(); - append(Atom::JavaScript, getCode(CMD_JS, CodeMarker::markerForLanguage(QLatin1String("JavaScript")))); - break; - case CMD_DIV: - leavePara(); - p1 = getArgument(true); - append(Atom::DivLeft, p1); - openedCommands.push(cmd); - break; - case CMD_ENDDIV: - leavePara(); - append(Atom::DivRight); - closeCommand(cmd); - break; - case CMD_CODELINE: - { - if (!quoting) { - if (priv->text.lastAtom()->type() == Atom::Code - && priv->text.lastAtom()->string().endsWith("\n\n")) - priv->text.lastAtom()->chopString(); - appendToCode("\n"); - } - else { - append(Atom::CodeQuoteCommand, cmdStr); - append(Atom::CodeQuoteArgument, " "); - } - } - break; - case CMD_DOTS: - { - if (!quoting) { - if (priv->text.lastAtom()->type() == Atom::Code - && priv->text.lastAtom()->string().endsWith("\n\n")) - priv->text.lastAtom()->chopString(); - - QString arg = getOptionalArgument(); - int indent = 4; - if (!arg.isEmpty()) - indent = arg.toInt(); - for (int i = 0; i < indent; ++i) - appendToCode(" "); - appendToCode("...\n"); - } - else { - append(Atom::CodeQuoteCommand, cmdStr); - QString arg = getOptionalArgument(); - if (arg.isEmpty()) - arg = "4"; - append(Atom::CodeQuoteArgument, arg); - } - } - break; - case CMD_ELSE: - if (preprocessorSkipping.size() > 0) { - if (preprocessorSkipping.top()) { - --numPreprocessorSkipping; - } - else { - ++numPreprocessorSkipping; - } - preprocessorSkipping.top() = !preprocessorSkipping.top(); - (void)getRestOfLine(); // ### should ensure that it's empty - if (numPreprocessorSkipping) - skipToNextPreprocessorCommand(); - } - else { - location().warning(tr("Unexpected '\\%1'").arg(cmdName(CMD_ELSE))); - } - break; - case CMD_ENDCHAPTER: - endSection(Doc::Chapter, cmd); - break; - case CMD_ENDCODE: - closeCommand(cmd); - break; - case CMD_ENDQML: - closeCommand(cmd); - break; - case CMD_ENDQMLTEXT: - append(Atom::EndQmlText); - break; - case CMD_ENDJS: - closeCommand(cmd); - break; - case CMD_ENDFOOTNOTE: - if (closeCommand(cmd)) { - leavePara(); - append(Atom::FootnoteRight); - paraState = InMultiLineParagraph; // ### - } - break; - case CMD_ENDIF: - if (preprocessorSkipping.count() > 0) { - if (preprocessorSkipping.pop()) - --numPreprocessorSkipping; - (void)getRestOfLine(); // ### should ensure that it's empty - if (numPreprocessorSkipping) - skipToNextPreprocessorCommand(); - } - else { - location().warning(tr("Unexpected '\\%1'").arg(cmdName(CMD_ENDIF))); - } - break; - case CMD_ENDLEGALESE: - if (closeCommand(cmd)) { - leavePara(); - append(Atom::LegaleseRight); - } - break; - case CMD_ENDLINK: - if (closeCommand(cmd)) { - if (priv->text.lastAtom()->type() == Atom::String - && priv->text.lastAtom()->string().endsWith(QLatin1Char(' '))) - priv->text.lastAtom()->chopString(); - append(Atom::FormattingRight, ATOM_FORMATTING_LINK); - } - break; - case CMD_ENDLIST: - if (closeCommand(cmd)) { - leavePara(); - if (openedLists.top().isStarted()) { - append(Atom::ListItemRight, - openedLists.top().styleString()); - append(Atom::ListRight, - openedLists.top().styleString()); - } - openedLists.pop(); - } - break; - case CMD_ENDMAPREF: - case CMD_ENDTOPICREF: - if (closeCommand(cmd)) { - ditarefs_.pop(); // zzz - } - break; - case CMD_ENDOMIT: - closeCommand(cmd); - break; - case CMD_ENDPART: - endSection(Doc::Part, cmd); - break; - case CMD_ENDQUOTATION: - if (closeCommand(cmd)) { - leavePara(); - append(Atom::QuotationRight); - } - break; - case CMD_ENDRAW: - location().warning(tr("Unexpected '\\%1'").arg(cmdName(CMD_ENDRAW))); - break; - case CMD_ENDSECTION1: - endSection(Doc::Section1, cmd); - break; - case CMD_ENDSECTION2: - endSection(Doc::Section2, cmd); - break; - case CMD_ENDSECTION3: - endSection(Doc::Section3, cmd); - break; - case CMD_ENDSECTION4: - endSection(Doc::Section4, cmd); - break; - case CMD_ENDSIDEBAR: - if (closeCommand(cmd)) { - leavePara(); - append(Atom::SidebarRight); - } - break; - case CMD_ENDTABLE: - if (closeCommand(cmd)) { - leaveTableRow(); - append(Atom::TableRight); - } - break; - case CMD_FOOTNOTE: - if (openCommand(cmd)) { - enterPara(); - append(Atom::FootnoteLeft); - paraState = OutsideParagraph; // ### - } - break; - case CMD_ANNOTATEDLIST: - append(Atom::AnnotatedList, getArgument()); - break; - case CMD_SINCELIST: - append(Atom::SinceList, getRestOfLine().simplified()); - break; - case CMD_GENERATELIST: - { - QString arg1 = getArgument(); - QString arg2 = getOptionalArgument(); - if (!arg2.isEmpty()) - arg1 += " " + arg2; - append(Atom::GeneratedList, arg1); - } - break; - case CMD_GRANULARITY: - priv->constructExtra(); - priv->extra->granularity_ = getSectioningUnit(); - break; - case CMD_HEADER: - if (openedCommands.top() == CMD_TABLE) { - leaveTableRow(); - append(Atom::TableHeaderLeft); - inTableHeader = true; - } - else { - if (openedCommands.contains(CMD_TABLE)) { - location().warning(tr("Cannot use '\\%1' within '\\%2'") - .arg(cmdName(CMD_HEADER)) - .arg(cmdName(openedCommands.top()))); - } - else { - location().warning(tr("Cannot use '\\%1' outside of '\\%2'") - .arg(cmdName(CMD_HEADER)) - .arg(cmdName(CMD_TABLE))); - } - } - break; - case CMD_I: - location().warning(tr("'\\i' is deprecated. Use '\\e' for italic or '\\li' for list item")); - case CMD_E: - startFormat(ATOM_FORMATTING_ITALIC, cmd); - break; - case CMD_HR: - leavePara(); - append(Atom::HR); - break; - case CMD_IF: - preprocessorSkipping.push(!Tokenizer::isTrue(getRestOfLine())); - if (preprocessorSkipping.top()) - ++numPreprocessorSkipping; - if (numPreprocessorSkipping) - skipToNextPreprocessorCommand(); - break; - case CMD_IMAGE: - leaveValueList(); - append(Atom::Image, getArgument()); - append(Atom::ImageText, getRestOfLine()); - break; - case CMD_IMPORTANT: - leavePara(); - enterPara(Atom::ImportantLeft, Atom::ImportantRight); - break; - case CMD_INCLUDE: - case CMD_INPUT: - { - QString fileName = getArgument(); - QString identifier = getRestOfLine(); - include(fileName, identifier); - } - break; - case CMD_INLINEIMAGE: - enterPara(); - append(Atom::InlineImage, getArgument()); - append(Atom::ImageText, getRestOfLine()); - append(Atom::String, " "); - break; - case CMD_INDEX: - if (paraState == OutsideParagraph) { - enterPara(); - indexStartedPara = true; - } - else { - const Atom *last = priv->text.lastAtom(); - if (indexStartedPara && - (last->type() != Atom::FormattingRight || - last->string() != ATOM_FORMATTING_INDEX)) - indexStartedPara = false; - } - startFormat(ATOM_FORMATTING_INDEX, cmd); - break; - case CMD_KEYWORD: - insertTarget(getRestOfLine(),true); - break; - case CMD_L: - enterPara(); - if (isLeftBracketAhead()) { - p2 = getBracketedArgument(); - } - if (isLeftBraceAhead()) { - p1 = getArgument(); - append(p1, p2); - if (!p2.isEmpty() && !(priv->text.lastAtom()->error().isEmpty())) { - location().warning(tr("Check parameter in '[ ]' of '\\l' command: '%1', " - "possible misspelling, or unrecognized module name") - .arg(priv->text.lastAtom()->error())); - } - if (isLeftBraceAhead()) { - currentLinkAtom = priv->text.lastAtom(); - startFormat(ATOM_FORMATTING_LINK, cmd); - } - else { - append(Atom::FormattingLeft, ATOM_FORMATTING_LINK); - append(Atom::String, cleanLink(p1)); - append(Atom::FormattingRight, ATOM_FORMATTING_LINK); - } - } - else { - p1 = getArgument(); - append(p1, p2); - if (!p2.isEmpty() && !(priv->text.lastAtom()->error().isEmpty())) { - location().warning(tr("Check parameter in '[ ]' of '\\l' command: '%1', " - "possible misspelling, or unrecognized module name") - .arg(priv->text.lastAtom()->error())); - } - append(Atom::FormattingLeft, ATOM_FORMATTING_LINK); - append(Atom::String, cleanLink(p1)); - append(Atom::FormattingRight, ATOM_FORMATTING_LINK); - } - p2.clear(); - break; - case CMD_LEGALESE: - leavePara(); - if (openCommand(cmd)) - append(Atom::LegaleseLeft); - docPrivate->hasLegalese = true; - break; - case CMD_LINK: - if (openCommand(cmd)) { - enterPara(); - p1 = getArgument(); - append(p1); - append(Atom::FormattingLeft, ATOM_FORMATTING_LINK); - skipSpacesOrOneEndl(); - } - break; - case CMD_LIST: - if (openCommand(cmd)) { - leavePara(); - openedLists.push(OpenedList(location(), - getOptionalArgument())); - } - break; - case CMD_TOPICREF: - case CMD_MAPREF: - if (openCommand(cmd)) { - DitaRef* t = 0; - if (cmd == CMD_MAPREF) - t = new MapRef(); - else - t = new TopicRef(); - t->setNavtitle(getArgument(true)); - if (cmd == CMD_MAPREF) - t->setHref(getArgument()); - else - t->setHref(getOptionalArgument()); - if (ditarefs_.isEmpty()) - priv->ditamap_.append(t); - else - ditarefs_.top()->appendSubref(t); - ditarefs_.push(t); - } - break; - case CMD_META: - priv->constructExtra(); - p1 = getArgument(); - priv->extra->metaMap_.insert(p1, getArgument()); - break; - case CMD_NEWCODE: - location().warning(tr("Unexpected '\\%1'").arg(cmdName(CMD_NEWCODE))); - break; - case CMD_NOTE: - leavePara(); - enterPara(Atom::NoteLeft, Atom::NoteRight); - break; - case CMD_O: - location().warning(tr("'\\o' is deprecated. Use '\\li'")); - case CMD_LI: - leavePara(); - if (openedCommands.top() == CMD_LIST) { - if (openedLists.top().isStarted()) { - append(Atom::ListItemRight, - openedLists.top().styleString()); - } - else { - append(Atom::ListLeft, - openedLists.top().styleString()); - } - openedLists.top().next(); - append(Atom::ListItemNumber, - openedLists.top().numberString()); - append(Atom::ListItemLeft, - openedLists.top().styleString()); - enterPara(); - } - else if (openedCommands.top() == CMD_TABLE) { - p1 = "1,1"; - p2.clear(); - if (isLeftBraceAhead()) { - p1 = getArgument(); - if (isLeftBraceAhead()) { - p2 = getArgument(); - } - } - - if (!inTableHeader && !inTableRow) { - location().warning(tr("Missing '\\%1' or '\\%2' before '\\%3'") - .arg(cmdName(CMD_HEADER)) - .arg(cmdName(CMD_ROW)) - .arg(cmdName(CMD_LI))); - append(Atom::TableRowLeft); - inTableRow = true; - } - else if (inTableItem) { - append(Atom::TableItemRight); - inTableItem = false; - } - - append(Atom::TableItemLeft, p1, p2); - inTableItem = true; - } - else { - location().warning(tr("Command '\\%1' outside of '\\%2' and '\\%3'") - .arg(cmdName(cmd)) - .arg(cmdName(CMD_LIST)) - .arg(cmdName(CMD_TABLE))); - } - break; - case CMD_OLDCODE: - leavePara(); - append(Atom::CodeOld, getCode(CMD_OLDCODE, marker)); - append(Atom::CodeNew, getCode(CMD_NEWCODE, marker)); - break; - case CMD_OMIT: - getUntilEnd(cmd); - break; - case CMD_OMITVALUE: - p1 = getArgument(); - if (!priv->enumItemList.contains(p1)) - priv->enumItemList.append(p1); - if (!priv->omitEnumItemList.contains(p1)) - priv->omitEnumItemList.append(p1); - break; - case CMD_PART: - startSection(Doc::Part, cmd); - break; - case CMD_PRINTLINE: - leavePara(); - if (!quoting) - appendToCode(quoter.quoteLine(location(), cmdStr, - getRestOfLine())); - else { - append(Atom::CodeQuoteCommand, cmdStr); - append(Atom::CodeQuoteArgument, getRestOfLine()); - } - break; - case CMD_PRINTTO: - leavePara(); - if (!quoting) - appendToCode(quoter.quoteTo(location(), cmdStr, - getRestOfLine())); - else { - append(Atom::CodeQuoteCommand, cmdStr); - append(Atom::CodeQuoteArgument, getRestOfLine()); - } - break; - case CMD_PRINTUNTIL: - leavePara(); - if (!quoting) - appendToCode(quoter.quoteUntil(location(), cmdStr, - getRestOfLine())); - else { - append(Atom::CodeQuoteCommand, cmdStr); - append(Atom::CodeQuoteArgument, getRestOfLine()); - } - break; - case CMD_QUOTATION: - if (openCommand(cmd)) { - leavePara(); - append(Atom::QuotationLeft); - } - break; - case CMD_QUOTEFILE: - { - leavePara(); - QString fileName = getArgument(); - Doc::quoteFromFile(location(), quoter, fileName); - if (!quoting) { - append(Atom::Code, - quoter.quoteTo(location(), cmdStr, QString())); - quoter.reset(); - } - else { - append(Atom::CodeQuoteCommand, cmdStr); - append(Atom::CodeQuoteArgument, fileName); - } - break; - } - case CMD_QUOTEFROMFILE: - leavePara(); - if (!quoting) - quoteFromFile(); - else { - append(Atom::CodeQuoteCommand, cmdStr); - append(Atom::CodeQuoteArgument, getArgument()); - } - break; - case CMD_QUOTEFUNCTION: - leavePara(); - marker = quoteFromFile(); - p1 = getRestOfLine(); - if (!quoting) { - quoter.quoteTo(location(), cmdStr, - slashed(marker->functionBeginRegExp(p1))); - append(Atom::Code, - quoter.quoteUntil(location(), cmdStr, - slashed(marker->functionEndRegExp(p1)))); - quoter.reset(); - } - else { - append(Atom::CodeQuoteCommand, cmdStr); - append(Atom::CodeQuoteArgument, slashed(marker->functionEndRegExp(p1))); - } - break; - case CMD_RAW: - leavePara(); - p1 = getRestOfLine(); - if (p1.isEmpty()) - location().warning(tr("Missing format name after '\\%1'") - .arg(cmdName(CMD_RAW))); - append(Atom::FormatIf, p1); - append(Atom::RawString, untabifyEtc(getUntilEnd(cmd))); - append(Atom::FormatElse); - append(Atom::FormatEndif); - break; - case CMD_ROW: - if (openedCommands.top() == CMD_TABLE) { - p1.clear(); - if (isLeftBraceAhead()) - p1 = getArgument(true); - leaveTableRow(); - append(Atom::TableRowLeft,p1); - inTableRow = true; - } - else { - if (openedCommands.contains(CMD_TABLE)) { - location().warning(tr("Cannot use '\\%1' within '\\%2'") - .arg(cmdName(CMD_ROW)) - .arg(cmdName(openedCommands.top()))); - } - else { - location().warning(tr("Cannot use '\\%1' outside of '\\%2'") - .arg(cmdName(CMD_ROW)) - .arg(cmdName(CMD_TABLE))); - } - } - break; - case CMD_SA: - parseAlso(); - break; - case CMD_SECTION1: - startSection(Doc::Section1, cmd); - break; - case CMD_SECTION2: - startSection(Doc::Section2, cmd); - break; - case CMD_SECTION3: - startSection(Doc::Section3, cmd); - break; - case CMD_SECTION4: - startSection(Doc::Section4, cmd); - break; - case CMD_SIDEBAR: - if (openCommand(cmd)) { - leavePara(); - append(Atom::SidebarLeft); - } - break; - case CMD_SKIPLINE: - leavePara(); - if (!quoting) - quoter.quoteLine(location(), - cmdStr, - getRestOfLine()); - else { - append(Atom::CodeQuoteCommand, cmdStr); - append(Atom::CodeQuoteArgument, getRestOfLine()); - } - break; - case CMD_SKIPTO: - leavePara(); - if (!quoting) - quoter.quoteTo(location(), - cmdStr, - getRestOfLine()); - else { - append(Atom::CodeQuoteCommand, cmdStr); - append(Atom::CodeQuoteArgument, getRestOfLine()); - } - break; - case CMD_SKIPUNTIL: - leavePara(); - if (!quoting) - quoter.quoteUntil(location(), - cmdStr, - getRestOfLine()); - else { - append(Atom::CodeQuoteCommand, cmdStr); - append(Atom::CodeQuoteArgument, getRestOfLine()); - } - break; - case CMD_SPAN: - p1 = ATOM_FORMATTING_SPAN + getArgument(true); - startFormat(p1, cmd); - break; - case CMD_SNIPPET: - leavePara(); - { - QString snippet = getArgument(); - QString identifier = getRestOfLine(); - if (quoting) { - append(Atom::SnippetCommand, cmdStr); - append(Atom::SnippetLocation, snippet); - append(Atom::SnippetIdentifier, identifier); - } - else { - marker = Doc::quoteFromFile(location(),quoter,snippet); - appendToCode(quoter.quoteSnippet(location(), identifier), marker->atomType()); - } - } - break; - case CMD_SUB: - startFormat(ATOM_FORMATTING_SUBSCRIPT, cmd); - break; - case CMD_SUP: - startFormat(ATOM_FORMATTING_SUPERSCRIPT, cmd); - break; - case CMD_TABLE: - //p1 = getRestOfLine(); - p1 = getOptionalArgument(); - p2 = getOptionalArgument(); - if (openCommand(cmd)) { - leavePara(); - append(Atom::TableLeft, p1, p2); - inTableHeader = false; - inTableRow = false; - inTableItem = false; - } - break; - case CMD_TABLEOFCONTENTS: - p1 = "1"; - if (isLeftBraceAhead()) - p1 = getArgument(); - p1 += QLatin1Char(','); - p1 += QString::number((int)getSectioningUnit()); - append(Atom::TableOfContents, p1); - break; - case CMD_TARGET: - insertTarget(getRestOfLine(),false); - break; - case CMD_TT: - startFormat(ATOM_FORMATTING_TELETYPE, cmd); - break; - case CMD_UICONTROL: - startFormat(ATOM_FORMATTING_UICONTROL, cmd); - break; - case CMD_UNDERLINE: - startFormat(ATOM_FORMATTING_UNDERLINE, cmd); - break; - case CMD_UNICODE: - enterPara(); - p1 = getArgument(); - { - bool ok; - uint unicodeChar = p1.toUInt(&ok, 0); - if (!ok || - (unicodeChar == 0x0000) || - (unicodeChar > 0xFFFE)) { - location().warning(tr("Invalid Unicode character '%1' specified " - "with '%2'") - .arg(p1, cmdName(CMD_UNICODE))); - } - else { - append(Atom::String, QChar(unicodeChar)); - } - } - break; - case CMD_VALUE: - leaveValue(); - if (openedLists.top().style() == OpenedList::Value) { - p1 = getArgument(); - if (!priv->enumItemList.contains(p1)) - priv->enumItemList.append(p1); - - openedLists.top().next(); - append(Atom::ListTagLeft, ATOM_LIST_VALUE); - append(Atom::String, p1); - append(Atom::ListTagRight, ATOM_LIST_VALUE); - append(Atom::ListItemLeft, ATOM_LIST_VALUE); - - skipSpacesOrOneEndl(); - if (isBlankLine()) - append(Atom::Nop); - } - else { - // ### problems - } - break; - case CMD_WARNING: - leavePara(); - enterPara(); - append(Atom::FormattingLeft, ATOM_FORMATTING_BOLD); - append(Atom::String, "Warning:"); - append(Atom::FormattingRight, ATOM_FORMATTING_BOLD); - append(Atom::String, " "); - break; - case CMD_OVERLOAD: - priv->metacommandsUsed.insert(cmdStr); - p1.clear(); - if (!isBlankLine()) - p1 = getRestOfLine(); - if (!p1.isEmpty()) { - append(Atom::ParaLeft); - append(Atom::String, "This function overloads "); - append(Atom::AutoLink,p1); - append(Atom::String, "."); - append(Atom::ParaRight); - } - else { - append(Atom::ParaLeft); - append(Atom::String,"This is an overloaded function."); - append(Atom::ParaRight); - p1 = getMetaCommandArgument(cmdStr); - } - priv->metaCommandMap[cmdStr].append(ArgLocPair(p1,location())); - break; - case NOT_A_CMD: - if (metaCommandSet.contains(cmdStr)) { - priv->metacommandsUsed.insert(cmdStr); - QString arg = getMetaCommandArgument(cmdStr); - priv->metaCommandMap[cmdStr].append(ArgLocPair(arg,location())); - if (possibleTopics.contains(cmdStr)) { - priv->topics_.append(Topic(cmdStr,arg)); - } - } - else if (macroHash()->contains(cmdStr)) { - const Macro ¯o = macroHash()->value(cmdStr); - int numPendingFi = 0; - QStringMap::ConstIterator d; - d = macro.otherDefs.constBegin(); - while (d != macro.otherDefs.constEnd()) { - append(Atom::FormatIf, d.key()); - expandMacro(cmdStr, *d, macro.numParams); - ++d; - - if (d == macro.otherDefs.constEnd()) { - append(Atom::FormatEndif); - } - else { - append(Atom::FormatElse); - numPendingFi++; - } - } - while (numPendingFi-- > 0) - append(Atom::FormatEndif); - - if (!macro.defaultDef.isEmpty()) { - if (!macro.otherDefs.isEmpty()) { - macro.defaultDefLocation.warning( - tr("Macro cannot have both " - "format-specific and qdoc- " - "syntax definitions")); - } - else { - location().push(macro.defaultDefLocation.filePath()); - in.insert(pos, expandMacroToString(cmdStr, macro.defaultDef, macro.numParams)); - len = in.length(); - openedInputs.push(pos + macro.defaultDef.length()); - } - } - } - else { - location().warning( - tr("Unknown command '\\%1'").arg(cmdStr), - detailsUnknownCommand(metaCommandSet,cmdStr)); - enterPara(); - append(Atom::UnknownCommand, cmdStr); - } - } - } - } - break; - case '{': - enterPara(); - appendChar('{'); - braceDepth++; - pos++; - break; - case '}': - { - braceDepth--; - pos++; - - QMap<int, QString>::Iterator f = pendingFormats.find(braceDepth); - if (f == pendingFormats.end()) { - enterPara(); - appendChar('}'); - } - else { - append(Atom::FormattingRight, *f); - if (*f == ATOM_FORMATTING_INDEX) { - if (indexStartedPara) - skipAllSpaces(); - } - else if (*f == ATOM_FORMATTING_LINK) { - // hack for C++ to support links like - // \l{QString::}{count()} - if (currentLinkAtom && - currentLinkAtom->string().endsWith("::")) { - QString suffix = Text::subText(currentLinkAtom, - priv->text.lastAtom()).toString(); - currentLinkAtom->appendString(suffix); - } - currentLinkAtom = 0; - } - pendingFormats.erase(f); - } - } - break; - default: - { - bool newWord; - switch (priv->text.lastAtom()->type()) { - case Atom::ParaLeft: - newWord = true; - break; - default: - newWord = false; - } - - if (paraState == OutsideParagraph) { - if (ch.isSpace()) { - ++pos; - newWord = false; - } - else { - enterPara(); - newWord = true; - } - } - else { - if (ch.isSpace()) { - ++pos; - if ((ch == '\n') && - (paraState == InSingleLineParagraph || - isBlankLine())) { - leavePara(); - newWord = false; - } - else { - appendChar(' '); - newWord = true; - } - } - else { - newWord = true; - } - } - - if (newWord) { - int startPos = pos; - int numInternalUppercase = 0; - int numLowercase = 0; - int numStrangeSymbols = 0; - - while (pos < len) { - unsigned char latin1Ch = in.at(pos).toLatin1(); - if (islower(latin1Ch)) { - ++numLowercase; - ++pos; - } - else if (isupper(latin1Ch)) { - if (pos > startPos) - ++numInternalUppercase; - ++pos; - } - else if (isdigit(latin1Ch)) { - if (pos > startPos) { - ++pos; - } - else { - break; - } - } - else if (latin1Ch == '_' || latin1Ch == '@') { - ++numStrangeSymbols; - ++pos; - } - else if (latin1Ch == ':' && pos < len - 1 - && in.at(pos + 1) == QLatin1Char(':')) { - ++numStrangeSymbols; - pos += 2; - } - else if (latin1Ch == '(') { - if (pos > startPos) { - if (pos < len - 1 && - in.at(pos + 1) == QLatin1Char(')')) { - ++numStrangeSymbols; - pos += 2; - break; - } - else { - // ### handle functions with signatures - // and function calls - break; - } - } - else { - break; - } - } - else { - break; - } - } - - if (pos == startPos) { - if (!ch.isSpace()) { - appendChar(ch); - ++pos; - } - } - else { - QString word = in.mid(startPos, pos - startPos); - // is word a C++ symbol or an English word? - if ((numInternalUppercase >= 1 && numLowercase >= 2) - || numStrangeSymbols > 0) { - if (word.startsWith(QString("__"))) - appendWord(word); - else - append(Atom::AutoLink, word); - } - else - appendWord(word); - } - } - } - } - } - leaveValueList(); - - // for compatibility - if (openedCommands.top() == CMD_LEGALESE) { - append(Atom::LegaleseRight); - openedCommands.pop(); - } - - if (openedCommands.top() != CMD_OMIT) { - location().warning(tr("Missing '\\%1'").arg(endCmdName(openedCommands.top()))); - } - else if (preprocessorSkipping.count() > 0) { - location().warning(tr("Missing '\\%1'").arg(cmdName(CMD_ENDIF))); - } - - if (currentSection > Doc::NoSection) { - append(Atom::SectionRight, QString::number(currentSection)); - currentSection = Doc::NoSection; - } - - if (priv->extra && priv->extra->granularity_ < priv->extra->section_) - priv->extra->granularity_ = priv->extra->section_; - priv->text.stripFirstAtom(); -} - -/*! - Returns the current location. - */ -Location &DocParser::location() -{ - while (!openedInputs.isEmpty() && openedInputs.top() <= pos) { - cachedLoc.pop(); - cachedPos = openedInputs.pop(); - } - while (cachedPos < pos) - cachedLoc.advance(in.at(cachedPos++)); - return cachedLoc; -} - -QString DocParser::detailsUnknownCommand(const QSet<QString> &metaCommandSet, - const QString &str) -{ - QSet<QString> commandSet = metaCommandSet; - int i = 0; - while (cmds[i].english != 0) { - commandSet.insert(*cmds[i].alias); - i++; - } - - if (aliasMap()->contains(str)) - return tr("The command '\\%1' was renamed '\\%2' by the configuration" - " file. Use the new name.") - .arg(str).arg((*aliasMap())[str]); - - QString best = nearestName(str, commandSet); - if (best.isEmpty()) - return QString(); - return tr("Maybe you meant '\\%1'?").arg(best); -} - -void DocParser::insertTarget(const QString &target, bool keyword) -{ - if (targetMap_.contains(target)) { - location().warning(tr("Duplicate target name '%1'").arg(target)); - targetMap_[target].warning(tr("(The previous occurrence is here)")); - } - else { - targetMap_.insert(target, location()); - priv->constructExtra(); - if (keyword) { - append(Atom::Keyword, target); - priv->extra->keywords_.append(priv->text.lastAtom()); - } - else { - append(Atom::Target, target); - priv->extra->targets_.append(priv->text.lastAtom()); - } - } -} - -void DocParser::include(const QString& fileName, const QString& identifier) -{ - if (location().depth() > 16) - location().fatal(tr("Too many nested '\\%1's").arg(cmdName(CMD_INCLUDE))); - - QString userFriendlyFilePath; - QString filePath = Doc::config()->getIncludeFilePath(fileName); -#if 0 - QString filePath = Config::findFile(location(), - sourceFiles, - sourceDirs, - fileName, - userFriendlyFilePath); -#endif - if (filePath.isEmpty()) { - location().warning(tr("Cannot find qdoc include file '%1'").arg(fileName)); - } - else { - QFile inFile(filePath); - if (!inFile.open(QFile::ReadOnly)) { - location().warning(tr("Cannot open qdoc include file '%1'") - .arg(userFriendlyFilePath)); - } - else { - location().push(userFriendlyFilePath); - - QTextStream inStream(&inFile); - QString includedStuff = inStream.readAll(); - inFile.close(); - - if (identifier.isEmpty()) { - in.insert(pos, includedStuff); - len = in.length(); - openedInputs.push(pos + includedStuff.length()); - } - else { - QStringList lineBuffer = includedStuff.split(QLatin1Char('\n')); - int i = 0; - int startLine = -1; - while (i < lineBuffer.size()) { - if (lineBuffer[i].startsWith("//!")) { - if (lineBuffer[i].contains(identifier)) { - startLine = i+1; - break; - } - } - ++i; - } - if (startLine < 0) { - location().warning(tr("Cannot find '%1' in '%2'") - .arg(identifier) - .arg(userFriendlyFilePath)); - return; - - } - QString result; - i = startLine; - do { - if (lineBuffer[i].startsWith("//!")) { - if (i<lineBuffer.size()) { - if (lineBuffer[i].contains(identifier)) { - break; - } - } - } - else - result += lineBuffer[i] + QLatin1Char('\n'); - ++i; - } while (i < lineBuffer.size()); - if (result.isEmpty()) { - location().warning(tr("Empty qdoc snippet '%1' in '%2'") - .arg(identifier) - .arg(userFriendlyFilePath)); - } - else { - in.insert(pos, result); - len = in.length(); - openedInputs.push(pos + result.length()); - } - } - } - } -} - -void DocParser::startFormat(const QString& format, int cmd) -{ - enterPara(); - - QMap<int, QString>::ConstIterator f = pendingFormats.constBegin(); - while (f != pendingFormats.constEnd()) { - if (*f == format) { - location().warning(tr("Cannot nest '\\%1' commands") - .arg(cmdName(cmd))); - return; - } - ++f; - } - - append(Atom::FormattingLeft, format); - - if (isLeftBraceAhead()) { - skipSpacesOrOneEndl(); - pendingFormats.insert(braceDepth, format); - ++braceDepth; - ++pos; - } - else { - append(Atom::String, getArgument()); - append(Atom::FormattingRight, format); - if (format == ATOM_FORMATTING_INDEX && indexStartedPara) { - skipAllSpaces(); - indexStartedPara = false; - } - } -} - -bool DocParser::openCommand(int cmd) -{ - int outer = openedCommands.top(); - bool ok = true; - - if (cmd != CMD_LINK) { - if (outer == CMD_LIST) { - ok = (cmd == CMD_FOOTNOTE || cmd == CMD_LIST); - } - else if (outer == CMD_SIDEBAR) { - ok = (cmd == CMD_LIST || - cmd == CMD_QUOTATION || - cmd == CMD_SIDEBAR); - } - else if (outer == CMD_QUOTATION) { - ok = (cmd == CMD_LIST); - } - else if (outer == CMD_TABLE) { - ok = (cmd == CMD_LIST || - cmd == CMD_FOOTNOTE || - cmd == CMD_QUOTATION); - } - else if (outer == CMD_FOOTNOTE || outer == CMD_LINK) { - ok = false; - } - else if (outer == CMD_TOPICREF) - ok = (cmd == CMD_TOPICREF || cmd == CMD_MAPREF); - else if (outer == CMD_MAPREF) - ok = false; - } - - if (ok) { - openedCommands.push(cmd); - } - else { - location().warning(tr("Can't use '\\%1' in '\\%2'").arg(cmdName(cmd)).arg(cmdName(outer))); - } - return ok; -} - -bool DocParser::closeCommand(int endCmd) -{ - if (endCmdFor(openedCommands.top()) == endCmd && openedCommands.size() > 1) { - openedCommands.pop(); - return true; - } - else { - bool contains = false; - QStack<int> opened2 = openedCommands; - while (opened2.size() > 1) { - if (endCmdFor(opened2.top()) == endCmd) { - contains = true; - break; - } - opened2.pop(); - } - - if (contains) { - while (endCmdFor(openedCommands.top()) != endCmd && openedCommands.size() > 1) { - location().warning(tr("Missing '\\%1' before '\\%2'") - .arg(endCmdName(openedCommands.top())) - .arg(cmdName(endCmd))); - openedCommands.pop(); - } - } - else { - location().warning(tr("Unexpected '\\%1'").arg(cmdName(endCmd))); - } - return false; - } -} - -void DocParser::startSection(Doc::Sections unit, int cmd) -{ - leaveValueList(); - - if (currentSection == Doc::NoSection) { - currentSection = (Doc::Sections) (unit); - priv->constructExtra(); - priv->extra->section_ = currentSection; - } - else - endSection(unit,cmd); - - append(Atom::SectionLeft, QString::number(unit)); - priv->constructExtra(); - priv->extra->tableOfContents_.append(priv->text.lastAtom()); - priv->extra->tableOfContentsLevels_.append(unit); - enterPara(Atom::SectionHeadingLeft, - Atom::SectionHeadingRight, - QString::number(unit)); - currentSection = unit; - -} - -void DocParser::endSection(int , int) // (int unit, int endCmd) -{ - leavePara(); - append(Atom::SectionRight, QString::number(currentSection)); - currentSection = (Doc::NoSection); -} - -void DocParser::parseAlso() -{ - leavePara(); - skipSpacesOnLine(); - while (pos < len && in[pos] != '\n') { - QString target; - QString str; - - if (in[pos] == '{') { - target = getArgument(); - skipSpacesOnLine(); - if (in[pos] == '{') { - str = getArgument(); - - // hack for C++ to support links like \l{QString::}{count()} - if (target.endsWith("::")) - target += str; - } - else { - str = target; - } -#ifdef QDOC2_COMPAT - } - else if (in[pos] == '\\' && in.mid(pos, 5) == "\\link") { - pos += 6; - target = getArgument(); - int endPos = in.indexOf("\\endlink", pos); - if (endPos != -1) { - str = in.mid(pos, endPos - pos).trimmed(); - pos = endPos + 8; - } -#endif - } - else { - target = getArgument(); - str = cleanLink(target); - } - - Text also; - also << Atom(Atom::Link, target) - << Atom(Atom::FormattingLeft, ATOM_FORMATTING_LINK) - << str - << Atom(Atom::FormattingRight, ATOM_FORMATTING_LINK); - priv->addAlso(also); - - skipSpacesOnLine(); - if (pos < len && in[pos] == ',') { - pos++; - skipSpacesOrOneEndl(); - } - else if (in[pos] != '\n') { - location().warning(tr("Missing comma in '\\%1'").arg(cmdName(CMD_SA))); - } - } -} - -void DocParser::append(Atom::AtomType type, const QString &string) -{ - Atom::AtomType lastType = priv->text.lastAtom()->type(); - if ((lastType == Atom::Code) && priv->text.lastAtom()->string().endsWith(QLatin1String("\n\n"))) - priv->text.lastAtom()->chopString(); - priv->text << Atom(type, string); -} - -void DocParser::append(const QString &string) -{ - Atom::AtomType lastType = priv->text.lastAtom()->type(); - if ((lastType == Atom::Code) && priv->text.lastAtom()->string().endsWith(QLatin1String("\n\n"))) - priv->text.lastAtom()->chopString(); - priv->text << Atom(string); // The Atom type is Link. -} - -void DocParser::append(Atom::AtomType type, const QString& p1, const QString& p2) -{ - Atom::AtomType lastType = priv->text.lastAtom()->type(); - if ((lastType == Atom::Code) && priv->text.lastAtom()->string().endsWith(QLatin1String("\n\n"))) - priv->text.lastAtom()->chopString(); - priv->text << Atom(type, p1, p2); -} - -void DocParser::append(const QString& p1, const QString& p2) -{ - Atom::AtomType lastType = priv->text.lastAtom()->type(); - if ((lastType == Atom::Code) && priv->text.lastAtom()->string().endsWith(QLatin1String("\n\n"))) - priv->text.lastAtom()->chopString(); - if (p2.isEmpty()) - priv->text << Atom(p1); // The Atom type is Link. - else - priv->text << LinkAtom(p1, p2); -} - -void DocParser::appendChar(QChar ch) -{ - if (priv->text.lastAtom()->type() != Atom::String) - append(Atom::String); - Atom *atom = priv->text.lastAtom(); - if (ch == QLatin1Char(' ')) { - if (!atom->string().endsWith(QLatin1Char(' '))) - atom->appendChar(QLatin1Char(' ')); - } - else - atom->appendChar(ch); -} - -void DocParser::appendWord(const QString &word) -{ - if (priv->text.lastAtom()->type() != Atom::String) { - append(Atom::String, word); - } - else - priv->text.lastAtom()->appendString(word); -} - -void DocParser::appendToCode(const QString& markedCode) -{ - Atom::AtomType lastType = priv->text.lastAtom()->type(); - if (lastType != Atom::Qml && lastType != Atom::Code && lastType != Atom::JavaScript) - append(Atom::Qml); - priv->text.lastAtom()->appendString(markedCode); -} - -void DocParser::appendToCode(const QString &markedCode, Atom::AtomType defaultType) -{ - Atom::AtomType lastType = priv->text.lastAtom()->type(); - if (lastType != Atom::Qml && lastType != Atom::Code && lastType != Atom::JavaScript) - append(defaultType, markedCode); - else - priv->text.lastAtom()->appendString(markedCode); -} - -void DocParser::startNewPara() -{ - leavePara(); - enterPara(); -} - -void DocParser::enterPara(Atom::AtomType leftType, - Atom::AtomType rightType, - const QString& string) -{ - if (paraState == OutsideParagraph) { - - if ((priv->text.lastAtom()->type() != Atom::ListItemLeft) && - (priv->text.lastAtom()->type() != Atom::DivLeft)) { - leaveValueList(); - } - - append(leftType, string); - indexStartedPara = false; - pendingParaLeftType = leftType; - pendingParaRightType = rightType; - pendingParaString = string; - if (leftType == Atom::SectionHeadingLeft) { - paraState = InSingleLineParagraph; - } - else { - paraState = InMultiLineParagraph; - } - skipSpacesOrOneEndl(); - } -} - -void DocParser::leavePara() -{ - if (paraState != OutsideParagraph) { - if (!pendingFormats.isEmpty()) { - location().warning(tr("Missing '}'")); - pendingFormats.clear(); - } - - if (priv->text.lastAtom()->type() == pendingParaLeftType) { - priv->text.stripLastAtom(); - } - else { - if (priv->text.lastAtom()->type() == Atom::String && - priv->text.lastAtom()->string().endsWith(QLatin1Char(' '))) { - priv->text.lastAtom()->chopString(); - } - append(pendingParaRightType, pendingParaString); - } - paraState = OutsideParagraph; - indexStartedPara = false; - pendingParaRightType = Atom::Nop; - pendingParaString.clear(); - } -} - -void DocParser::leaveValue() -{ - leavePara(); - if (openedLists.isEmpty()) { - openedLists.push(OpenedList(OpenedList::Value)); - append(Atom::ListLeft, ATOM_LIST_VALUE); - } - else { - if (priv->text.lastAtom()->type() == Atom::Nop) - priv->text.stripLastAtom(); - append(Atom::ListItemRight, ATOM_LIST_VALUE); - } -} - -void DocParser::leaveValueList() -{ - leavePara(); - if (!openedLists.isEmpty() && - (openedLists.top().style() == OpenedList::Value)) { - if (priv->text.lastAtom()->type() == Atom::Nop) - priv->text.stripLastAtom(); - append(Atom::ListItemRight, ATOM_LIST_VALUE); - append(Atom::ListRight, ATOM_LIST_VALUE); - openedLists.pop(); - } -} - -void DocParser::leaveTableRow() -{ - if (inTableItem) { - leavePara(); - append(Atom::TableItemRight); - inTableItem = false; - } - if (inTableHeader) { - append(Atom::TableHeaderRight); - inTableHeader = false; - } - if (inTableRow) { - append(Atom::TableRowRight); - inTableRow = false; - } -} - -CodeMarker *DocParser::quoteFromFile() -{ - return Doc::quoteFromFile(location(), quoter, getArgument()); -} - -void DocParser::expandMacro(const QString &name, - const QString &def, - int numParams) -{ - if (numParams == 0) { - append(Atom::RawString, def); - } - else { - QStringList args; - QString rawString; - - for (int i = 0; i < numParams; i++) { - if (numParams == 1 || isLeftBraceAhead()) { - args << getArgument(true); - } - else { - location().warning(tr("Macro '\\%1' invoked with too few" - " arguments (expected %2, got %3)") - .arg(name).arg(numParams).arg(i)); - break; - } - } - - int j = 0; - while (j < def.size()) { - int paramNo; - if (((paramNo = def[j].unicode()) >= 1) && - (paramNo <= numParams)) { - if (!rawString.isEmpty()) { - append(Atom::RawString, rawString); - rawString.clear(); - } - append(Atom::String, args[paramNo - 1]); - j += 1; - } - else { - rawString += def[j++]; - } - } - if (!rawString.isEmpty()) - append(Atom::RawString, rawString); - } -} - -QString DocParser::expandMacroToString(const QString &name, const QString &def, int numParams) -{ - if (numParams == 0) { - return def; - } - else { - QStringList args; - QString rawString; - - for (int i = 0; i < numParams; i++) { - if (numParams == 1 || isLeftBraceAhead()) { - args << getArgument(true); - } - else { - location().warning(tr("Macro '\\%1' invoked with too few" - " arguments (expected %2, got %3)") - .arg(name).arg(numParams).arg(i)); - break; - } - } - - int j = 0; - while (j < def.size()) { - int paramNo; - if (((paramNo = def[j].unicode()) >= 1) && - (paramNo <= numParams)) { - rawString += args[paramNo - 1]; - j += 1; - } - else { - rawString += def[j++]; - } - } - return rawString; - } -} - -Doc::Sections DocParser::getSectioningUnit() -{ - QString name = getOptionalArgument(); - - if (name == "part") { - return Doc::Part; - } - else if (name == "chapter") { - return Doc::Chapter; - } - else if (name == "section1") { - return Doc::Section1; - } - else if (name == "section2") { - return Doc::Section2; - } - else if (name == "section3") { - return Doc::Section3; - } - else if (name == "section4") { - return Doc::Section4; - } - else if (name.isEmpty()) { - return Doc::NoSection; - } - else { - location().warning(tr("Invalid section '%1'").arg(name)); - return Doc::NoSection; - } -} - -/*! - Gets an argument that is enclosed in braces and returns it - without the enclosing braces. On entry, the current character - is the left brace. On exit, the current character is the one - that comes after the right brace. - - If \a verbatim is true, extra whitespace is retained in the - returned string. Otherwise, extra whitespace is removed. - */ -QString DocParser::getBracedArgument(bool verbatim) -{ - QString arg; - int delimDepth = 0; - if (pos < (int) in.length() && in[pos] == '{') { - pos++; - while (pos < (int) in.length() && delimDepth >= 0) { - switch (in[pos].unicode()) { - case '{': - delimDepth++; - arg += QLatin1Char('{'); - pos++; - break; - case '}': - delimDepth--; - if (delimDepth >= 0) - arg += QLatin1Char('}'); - pos++; - break; - case '\\': - if (verbatim) { - arg += in[pos]; - pos++; - } - else { - pos++; - if (pos < (int) in.length()) { - if (in[pos].isLetterOrNumber()) - break; - arg += in[pos]; - if (in[pos].isSpace()) { - skipAllSpaces(); - } - else { - pos++; - } - } - } - break; - default: - if (in[pos].isSpace() && !verbatim) - arg += QChar(' '); - else - arg += in[pos]; - pos++; - } - } - if (delimDepth > 0) - location().warning(tr("Missing '}'")); - } - return arg; -} - -/*! - Typically, an argument ends at the next white-space. However, - braces can be used to group words: - - {a few words} - - Also, opening and closing parentheses have to match. Thus, - - printf("%d\n", x) - - is an argument too, although it contains spaces. Finally, - trailing punctuation is not included in an argument, nor is 's. -*/ -QString DocParser::getArgument(bool verbatim) -{ - skipSpacesOrOneEndl(); - - int delimDepth = 0; - int startPos = pos; - QString arg = getBracedArgument(verbatim); - if (arg.isEmpty()) { - while ((pos < in.length()) && - ((delimDepth > 0) || ((delimDepth == 0) && !in[pos].isSpace()))) { - switch (in[pos].unicode()) { - case '(': - case '[': - case '{': - delimDepth++; - arg += in[pos]; - pos++; - break; - case ')': - case ']': - case '}': - delimDepth--; - if (pos == startPos || delimDepth >= 0) { - arg += in[pos]; - pos++; - } - break; - case '\\': - if (verbatim) { - arg += in[pos]; - pos++; - } - else { - pos++; - if (pos < (int) in.length()) { - if (in[pos].isLetterOrNumber()) - break; - arg += in[pos]; - if (in[pos].isSpace()) { - skipAllSpaces(); - } - else { - pos++; - } - } - } - break; - default: - arg += in[pos]; - pos++; - } - } - if ((arg.length() > 1) && - (QString(".,:;!?").indexOf(in[pos - 1]) != -1) && - !arg.endsWith("...")) { - arg.truncate(arg.length() - 1); - pos--; - } - if (arg.length() > 2 && in.mid(pos - 2, 2) == "'s") { - arg.truncate(arg.length() - 2); - pos -= 2; - } - } - return arg.simplified(); -} - -/*! - Gets an argument that is enclosed in brackets and returns it - without the enclosing brackets. On entry, the current character - is the left bracket. On exit, the current character is the one - that comes after the right bracket. - */ -QString DocParser::getBracketedArgument() -{ - QString arg; - int delimDepth = 0; - skipSpacesOrOneEndl(); - if (pos < in.length() && in[pos] == '[') { - pos++; - while (pos < in.length() && delimDepth >= 0) { - switch (in[pos].unicode()) { - case '[': - delimDepth++; - arg += QLatin1Char('['); - pos++; - break; - case ']': - delimDepth--; - if (delimDepth >= 0) - arg += QLatin1Char(']'); - pos++; - break; - case '\\': - arg += in[pos]; - pos++; - break; - default: - arg += in[pos]; - pos++; - } - } - if (delimDepth > 0) - location().warning(tr("Missing ']'")); - } - return arg; -} - -QString DocParser::getOptionalArgument() -{ - skipSpacesOrOneEndl(); - if (pos + 1 < (int) in.length() && in[pos] == '\\' && - in[pos + 1].isLetterOrNumber()) { - return QString(); - } - else { - return getArgument(); - } -} - -QString DocParser::getRestOfLine() -{ - QString t; - - skipSpacesOnLine(); - - bool trailingSlash = false; - - do { - int begin = pos; - - while (pos < in.size() && in[pos] != '\n') { - if (in[pos] == '\\' && !trailingSlash) { - trailingSlash = true; - ++pos; - while ((pos < in.size()) && - in[pos].isSpace() && - (in[pos] != '\n')) - ++pos; - } - else { - trailingSlash = false; - ++pos; - } - } - - if (!t.isEmpty()) - t += QLatin1Char(' '); - t += in.mid(begin, pos - begin).simplified(); - - if (trailingSlash) { - t.chop(1); - t = t.simplified(); - } - if (pos < in.size()) - ++pos; - } while (pos < in.size() && trailingSlash); - - return t; -} - -/*! - The metacommand argument is normally the remaining text to - the right of the metacommand itself. The extra blanks are - stripped and the argument string is returned. - */ -QString DocParser::getMetaCommandArgument(const QString &cmdStr) -{ - skipSpacesOnLine(); - - int begin = pos; - int parenDepth = 0; - - while (pos < in.size() && (in[pos] != '\n' || parenDepth > 0)) { - if (in.at(pos) == '(') - ++parenDepth; - else if (in.at(pos) == ')') - --parenDepth; - - ++pos; - } - if (pos == in.size() && parenDepth > 0) { - pos = begin; - location().warning(tr("Unbalanced parentheses in '%1'").arg(cmdStr)); - } - - QString t = in.mid(begin, pos - begin).simplified(); - skipSpacesOnLine(); - return t; -} - -QString DocParser::getUntilEnd(int cmd) -{ - int endCmd = endCmdFor(cmd); - QRegExp rx("\\\\" + cmdName(endCmd) + "\\b"); - QString t; - int end = rx.indexIn(in, pos); - - if (end == -1) { - location().warning(tr("Missing '\\%1'").arg(cmdName(endCmd))); - pos = in.length(); - } - else { - t = in.mid(pos, end - pos); - pos = end + rx.matchedLength(); - } - return t; -} - -QString DocParser::getCode(int cmd, CodeMarker *marker) -{ - QString code = untabifyEtc(getUntilEnd(cmd)); - int indent = indentLevel(code); - if (indent < minIndent) - minIndent = indent; - code = unindent(minIndent, code); - if (!marker) - marker = CodeMarker::markerForCode(code); - return marker->markedUpCode(code, 0, location()); -} - -/*! - Was used only for generating doxygen output. - */ -QString DocParser::getUnmarkedCode(int cmd) -{ - QString code = getUntilEnd(cmd); - return code; -} - -bool DocParser::isBlankLine() -{ - int i = pos; - - while (i < len && in[i].isSpace()) { - if (in[i] == '\n') - return true; - i++; - } - return false; -} - -bool DocParser::isLeftBraceAhead() -{ - int numEndl = 0; - int i = pos; - - while (i < len && in[i].isSpace() && numEndl < 2) { - // ### bug with '\\' - if (in[i] == '\n') - numEndl++; - i++; - } - return numEndl < 2 && i < len && in[i] == '{'; -} - -bool DocParser::isLeftBracketAhead() -{ - int numEndl = 0; - int i = pos; - - while (i < len && in[i].isSpace() && numEndl < 2) { - // ### bug with '\\' - if (in[i] == '\n') - numEndl++; - i++; - } - return numEndl < 2 && i < len && in[i] == '['; -} - -/*! - Skips to the next non-space character or EOL. - */ -void DocParser::skipSpacesOnLine() -{ - while ((pos < in.length()) && - in[pos].isSpace() && - (in[pos].unicode() != '\n')) - ++pos; -} - -/*! - Skips spaces and on EOL. - */ -void DocParser::skipSpacesOrOneEndl() -{ - int firstEndl = -1; - while (pos < (int) in.length() && in[pos].isSpace()) { - QChar ch = in[pos]; - if (ch == '\n') { - if (firstEndl == -1) { - firstEndl = pos; - } - else { - pos = firstEndl; - break; - } - } - pos++; - } -} - -void DocParser::skipAllSpaces() -{ - while (pos < len && in[pos].isSpace()) - pos++; -} - -void DocParser::skipToNextPreprocessorCommand() -{ - QRegExp rx("\\\\(?:" + cmdName(CMD_IF) + QLatin1Char('|') + - cmdName(CMD_ELSE) + QLatin1Char('|') + - cmdName(CMD_ENDIF) + ")\\b"); - int end = rx.indexIn(in, pos + 1); // ### + 1 necessary? - - if (end == -1) - pos = in.length(); - else - pos = end; -} - -int DocParser::endCmdFor(int cmd) -{ - switch (cmd) { - case CMD_BADCODE: - return CMD_ENDCODE; - case CMD_CHAPTER: - return CMD_ENDCHAPTER; - case CMD_CODE: - return CMD_ENDCODE; - case CMD_DIV: - return CMD_ENDDIV; - case CMD_QML: - return CMD_ENDQML; - case CMD_QMLTEXT: - return CMD_ENDQMLTEXT; - case CMD_JS: - return CMD_ENDJS; - case CMD_FOOTNOTE: - return CMD_ENDFOOTNOTE; - case CMD_LEGALESE: - return CMD_ENDLEGALESE; - case CMD_LINK: - return CMD_ENDLINK; - case CMD_LIST: - return CMD_ENDLIST; - case CMD_NEWCODE: - return CMD_ENDCODE; - case CMD_OLDCODE: - return CMD_NEWCODE; - case CMD_OMIT: - return CMD_ENDOMIT; - case CMD_PART: - return CMD_ENDPART; - case CMD_QUOTATION: - return CMD_ENDQUOTATION; - case CMD_RAW: - return CMD_ENDRAW; - case CMD_SECTION1: - return CMD_ENDSECTION1; - case CMD_SECTION2: - return CMD_ENDSECTION2; - case CMD_SECTION3: - return CMD_ENDSECTION3; - case CMD_SECTION4: - return CMD_ENDSECTION4; - case CMD_SIDEBAR: - return CMD_ENDSIDEBAR; - case CMD_TABLE: - return CMD_ENDTABLE; - case CMD_TOPICREF: - return CMD_ENDTOPICREF; - case CMD_MAPREF: - return CMD_ENDMAPREF; - default: - return cmd; - } -} - -QString DocParser::cmdName(int cmd) -{ - return *cmds[cmd].alias; -} - -QString DocParser::endCmdName(int cmd) -{ - return cmdName(endCmdFor(cmd)); -} - -QString DocParser::untabifyEtc(const QString& str) -{ - QString result; - result.reserve(str.length()); - int column = 0; - - for (int i = 0; i < str.length(); i++) { - const QChar c = str.at(i); - if (c == QLatin1Char('\r')) - continue; - if (c == QLatin1Char('\t')) { - result += &" "[column % tabSize]; - column = ((column / tabSize) + 1) * tabSize; - continue; - } - if (c == QLatin1Char('\n')) { - while (result.endsWith(QLatin1Char(' '))) - result.chop(1); - result += c; - column = 0; - continue; - } - result += c; - column++; - } - - while (result.endsWith("\n\n")) - result.truncate(result.length() - 1); - while (result.startsWith(QLatin1Char('\n'))) - result = result.mid(1); - - return result; -} - -int DocParser::indentLevel(const QString& str) -{ - int minIndent = INT_MAX; - int column = 0; - - for (int i = 0; i < (int) str.length(); i++) { - if (str[i] == '\n') { - column = 0; - } - else { - if (str[i] != ' ' && column < minIndent) - minIndent = column; - column++; - } - } - return minIndent; -} - -QString DocParser::unindent(int level, const QString& str) -{ - if (level == 0) - return str; - - QString t; - int column = 0; - - for (int i = 0; i < (int) str.length(); i++) { - if (str[i] == QLatin1Char('\n')) { - t += '\n'; - column = 0; - } - else { - if (column >= level) - t += str[i]; - column++; - } - } - return t; -} - -QString DocParser::slashed(const QString& str) -{ - QString result = str; - result.replace(QLatin1Char('/'), "\\/"); - return QLatin1Char('/') + result + QLatin1Char('/'); -} - -/*! - Parse the qdoc comment \a source. Build up a list of all the topic - commands found including their arguments. This constructor is used - when there can be more than one topic command in theqdoc comment. - Normally, there is only one topic command in a qdoc comment, but in - QML documentation, there is the case where the qdoc \e{qmlproperty} - command can appear multiple times in a qdoc comment. - */ -Doc::Doc(const Location& start_loc, - const Location& end_loc, - const QString& source, - const QSet<QString>& metaCommandSet, - const QSet<QString>& topics) -{ - priv = new DocPrivate(start_loc,end_loc,source); - DocParser parser; - parser.parse(source,priv,metaCommandSet,topics); -} - -Doc::Doc(const Doc& doc) - : priv(0) -{ - operator=(doc); -} - -Doc::~Doc() -{ - if (priv && priv->deref()) - delete priv; -} - -Doc &Doc::operator=(const Doc& doc) -{ - if (doc.priv) - doc.priv->ref(); - if (priv && priv->deref()) - delete priv; - priv = doc.priv; - return *this; -} - -void Doc::renameParameters(const QStringList &oldNames, - const QStringList &newNames) -{ - if (priv && oldNames != newNames) { - detach(); - - priv->params = newNames.toSet(); - - Atom *atom = priv->text.firstAtom(); - while (atom) { - if (atom->type() == Atom::FormattingLeft - && atom->string() == ATOM_FORMATTING_PARAMETER) { - atom = atom->next(); - if (!atom) - return; - int index = oldNames.indexOf(atom->string()); - if (index != -1 && index < newNames.count()) - atom->setString(newNames.at(index)); - } - atom = atom->next(); - } - } -} - -void Doc::simplifyEnumDoc() -{ - if (priv) { - if (priv->isEnumDocSimplifiable()) { - detach(); - - Text newText; - - Atom *atom = priv->text.firstAtom(); - while (atom) { - if ((atom->type() == Atom::ListLeft) && - (atom->string() == ATOM_LIST_VALUE)) { - while (atom && ((atom->type() != Atom::ListRight) || - (atom->string() != ATOM_LIST_VALUE))) - atom = atom->next(); - if (atom) - atom = atom->next(); - } - else { - newText << *atom; - atom = atom->next(); - } - } - priv->text = newText; - } - } -} - -void Doc::setBody(const Text &text) -{ - detach(); - priv->text = text; -} - -/*! - Returns the starting location of a qdoc comment. - */ -const Location &Doc::location() const -{ - static const Location dummy; - return priv == 0 ? dummy : priv->start_loc; -} - -/*! - Returns the starting location of a qdoc comment. - */ -const Location& Doc::startLocation() const -{ - return location(); -} - -/*! - Returns the ending location of a qdoc comment. - */ -const Location& Doc::endLocation() const -{ - static const Location dummy; - return priv == 0 ? dummy : priv->end_loc; -} - -const QString &Doc::source() const -{ - static QString null; - return priv == 0 ? null : priv->src; -} - -bool Doc::isEmpty() const -{ - return priv == 0 || priv->src.isEmpty(); -} - -const Text& Doc::body() const -{ - static const Text dummy; - return priv == 0 ? dummy : priv->text; -} - -Text Doc::briefText(bool inclusive) const -{ - return body().subText(Atom::BriefLeft, Atom::BriefRight, 0, inclusive); -} - -Text Doc::trimmedBriefText(const QString &className) const -{ - QString classNameOnly = className; - if (className.contains("::")) - classNameOnly = className.split("::").last(); - - Text originalText = briefText(); - Text resultText; - const Atom *atom = originalText.firstAtom(); - if (atom) { - QString briefStr; - QString whats; - /* - This code is really ugly. The entire \brief business - should be rethought. - */ - while (atom) { - if (atom->type() == Atom::AutoLink || atom->type() == Atom::String) { - briefStr += atom->string(); - } - atom = atom->next(); - } - - QStringList w = briefStr.split(QLatin1Char(' ')); - if (!w.isEmpty() && w.first() == "Returns") { - } - else { - if (!w.isEmpty() && w.first() == "The") - w.removeFirst(); - - if (!w.isEmpty() && (w.first() == className || w.first() == classNameOnly)) - w.removeFirst(); - - if (!w.isEmpty() && ((w.first() == "class") || - (w.first() == "function") || - (w.first() == "macro") || - (w.first() == "widget") || - (w.first() == "namespace") || - (w.first() == "header"))) - w.removeFirst(); - - if (!w.isEmpty() && (w.first() == "is" || w.first() == "provides")) - w.removeFirst(); - - if (!w.isEmpty() && (w.first() == "a" || w.first() == "an")) - w.removeFirst(); - } - - whats = w.join(' '); - - if (whats.endsWith(QLatin1Char('.'))) - whats.truncate(whats.length() - 1); - - if (!whats.isEmpty()) - whats[0] = whats[0].toUpper(); - - // ### move this once \brief is abolished for properties - resultText << whats; - } - return resultText; -} - -Text Doc::legaleseText() const -{ - if (priv == 0 || !priv->hasLegalese) - return Text(); - else - return body().subText(Atom::LegaleseLeft, Atom::LegaleseRight); -} - -Doc::Sections Doc::granularity() const -{ - if (priv == 0 || priv->extra == 0) { - return DocPrivateExtra().granularity_; - } - else { - return priv->extra->granularity_; - } -} - -const QSet<QString> &Doc::parameterNames() const -{ - return priv == 0 ? *null_Set_QString() : priv->params; -} - -const QStringList &Doc::enumItemNames() const -{ - return priv == 0 ? *null_QStringList() : priv->enumItemList; -} - -const QStringList &Doc::omitEnumItemNames() const -{ - return priv == 0 ? *null_QStringList() : priv->omitEnumItemList; -} - -const QSet<QString> &Doc::metaCommandsUsed() const -{ - return priv == 0 ? *null_Set_QString() : priv->metacommandsUsed; -} - -/*! - Returns a reference to the list of topic commands used in the - current qdoc comment. Normally there is only one, but there - can be multiple \e{qmlproperty} commands, for example. - */ -const TopicList& Doc::topicsUsed() const -{ - return priv == 0 ? *nullTopicList() : priv->topics_; -} - -ArgList Doc::metaCommandArgs(const QString& metacommand) const -{ - return priv == 0 ? ArgList() : priv->metaCommandMap.value(metacommand); -} - -const QList<Text> &Doc::alsoList() const -{ - return priv == 0 ? *null_QList_Text() : priv->alsoList; -} - -bool Doc::hasTableOfContents() const -{ - return priv && priv->extra && !priv->extra->tableOfContents_.isEmpty(); -} - -bool Doc::hasKeywords() const -{ - return priv && priv->extra && !priv->extra->keywords_.isEmpty(); -} - -bool Doc::hasTargets() const -{ - return priv && priv->extra && !priv->extra->targets_.isEmpty(); -} - -const QList<Atom *> &Doc::tableOfContents() const -{ - priv->constructExtra(); - return priv->extra->tableOfContents_; -} - -const QVector<int> &Doc::tableOfContentsLevels() const -{ - priv->constructExtra(); - return priv->extra->tableOfContentsLevels_; -} - -const QList<Atom *> &Doc::keywords() const -{ - priv->constructExtra(); - return priv->extra->keywords_; -} - -const QList<Atom *> &Doc::targets() const -{ - priv->constructExtra(); - return priv->extra->targets_; -} - -const QStringMultiMap &Doc::metaTagMap() const -{ - return priv && priv->extra ? priv->extra->metaMap_ : *null_QStringMultiMap(); -} - -const Config* Doc::config_ = 0; - -void Doc::initialize(const Config& config) -{ - DocParser::tabSize = config.getInt(CONFIG_TABSIZE); - DocParser::exampleFiles = config.getCanonicalPathList(CONFIG_EXAMPLES); - DocParser::exampleDirs = config.getCanonicalPathList(CONFIG_EXAMPLEDIRS); - DocParser::sourceFiles = config.getCanonicalPathList(CONFIG_SOURCES); - DocParser::sourceDirs = config.getCanonicalPathList(CONFIG_SOURCEDIRS); - DocParser::quoting = config.getBool(CONFIG_QUOTINGINFORMATION); - - QmlTypeNode::qmlOnly = config.getBool(CONFIG_QMLONLY); - QStringMap reverseAliasMap; - config_ = &config; - - QSet<QString> commands = config.subVars(CONFIG_ALIAS); - QSet<QString>::ConstIterator c = commands.constBegin(); - while (c != commands.constEnd()) { - QString alias = config.getString(CONFIG_ALIAS + Config::dot + *c); - if (reverseAliasMap.contains(alias)) { - config.lastLocation().warning(tr("Command name '\\%1' cannot stand" - " for both '\\%2' and '\\%3'") - .arg(alias) - .arg(reverseAliasMap[alias]) - .arg(*c)); - } - else { - reverseAliasMap.insert(alias, *c); - } - aliasMap()->insert(*c, alias); - ++c; - } - - int i = 0; - while (cmds[i].english) { - cmds[i].alias = new QString(alias(cmds[i].english)); - cmdHash()->insert(*cmds[i].alias, cmds[i].no); - - if (cmds[i].no != i) - Location::internalError(tr("command %1 missing").arg(i)); - i++; - } - - QSet<QString> macroNames = config.subVars(CONFIG_MACRO); - QSet<QString>::ConstIterator n = macroNames.constBegin(); - while (n != macroNames.constEnd()) { - QString macroDotName = CONFIG_MACRO + Config::dot + *n; - Macro macro; - macro.numParams = -1; - macro.defaultDef = config.getString(macroDotName); - if (!macro.defaultDef.isEmpty()) { - macro.defaultDefLocation = config.lastLocation(); - macro.numParams = Config::numParams(macro.defaultDef); - } - bool silent = false; - - QSet<QString> formats = config.subVars(macroDotName); - QSet<QString>::ConstIterator f = formats.constBegin(); - while (f != formats.constEnd()) { - QString def = config.getString(macroDotName + Config::dot + *f); - if (!def.isEmpty()) { - macro.otherDefs.insert(*f, def); - int m = Config::numParams(def); - if (macro.numParams == -1) { - macro.numParams = m; - } - else if (macro.numParams != m) { - if (!silent) { - QString other = tr("default"); - if (macro.defaultDef.isEmpty()) - other = macro.otherDefs.constBegin().key(); - config.lastLocation().warning(tr("Macro '\\%1' takes" - " inconsistent number" - " of arguments (%2" - " %3, %4 %5)") - .arg(*n) - .arg(*f) - .arg(m) - .arg(other) - .arg(macro.numParams)); - silent = true; - } - if (macro.numParams < m) - macro.numParams = m; - } - } - ++f; - } - - if (macro.numParams != -1) - macroHash()->insert(*n, macro); - ++n; - } -} - -/*! - All the heap allocated variables are deleted. - */ -void Doc::terminate() -{ - DocParser::exampleFiles.clear(); - DocParser::exampleDirs.clear(); - DocParser::sourceFiles.clear(); - DocParser::sourceDirs.clear(); - aliasMap()->clear(); - cmdHash()->clear(); - macroHash()->clear(); - - int i = 0; - while (cmds[i].english) { - delete cmds[i].alias; - cmds[i].alias = 0; - ++i; - } -} - -QString Doc::alias(const QString &english) -{ - return aliasMap()->value(english, english); -} - -/*! - Trims the deadwood out of \a str. i.e., this function - cleans up \a str. - */ -void Doc::trimCStyleComment(Location& location, QString& str) -{ - QString cleaned; - Location m = location; - bool metAsterColumn = true; - int asterColumn = location.columnNo() + 1; - int i; - - for (i = 0; i < (int) str.length(); i++) { - if (m.columnNo() == asterColumn) { - if (str[i] != '*') - break; - cleaned += ' '; - metAsterColumn = true; - } - else { - if (str[i] == '\n') { - if (!metAsterColumn) - break; - metAsterColumn = false; - } - cleaned += str[i]; - } - m.advance(str[i]); - } - if (cleaned.length() == str.length()) - str = cleaned; - - for (int i = 0; i < 3; i++) - location.advance(str[i]); - str = str.mid(3, str.length() - 5); -} - -CodeMarker *Doc::quoteFromFile(const Location &location, - Quoter "er, - const QString &fileName) -{ - quoter.reset(); - - QString code; - - QString userFriendlyFilePath; - QString filePath = Config::findFile(location, - DocParser::exampleFiles, - DocParser::exampleDirs, - fileName, userFriendlyFilePath); - if (filePath.isEmpty()) { - QString details = QLatin1String("Example directories: ") + DocParser::exampleDirs.join(QLatin1Char(' ')); - if (!DocParser::exampleFiles.isEmpty()) - details += QLatin1String(", example files: ") + DocParser::exampleFiles.join(QLatin1Char(' ')); - location.warning(tr("Cannot find file to quote from: '%1'").arg(fileName), details); - } - else { - QFile inFile(filePath); - if (!inFile.open(QFile::ReadOnly)) { - location.warning(tr("Cannot open file to quote from: '%1'").arg(userFriendlyFilePath)); - } - else { - QTextStream inStream(&inFile); - code = DocParser::untabifyEtc(inStream.readAll()); - } - } - - QString dirPath = QFileInfo(filePath).path(); - CodeMarker *marker = CodeMarker::markerForFileName(fileName); - quoter.quoteFromFile(userFriendlyFilePath, code, marker->markedUpCode(code, 0, location)); - return marker; -} - -QString Doc::canonicalTitle(const QString &title) -{ - // The code below is equivalent to the following chunk, but _much_ - // faster (accounts for ~10% of total running time) - // - // QRegExp attributeExpr("[^A-Za-z0-9]+"); - // QString result = title.toLower(); - // result.replace(attributeExpr, " "); - // result = result.simplified(); - // result.replace(QLatin1Char(' '), QLatin1Char('-')); - - QString result; - result.reserve(title.size()); - - bool dashAppended = false; - bool begun = false; - int lastAlnum = 0; - for (int i = 0; i != title.size(); ++i) { - uint c = title.at(i).unicode(); - if (c >= 'A' && c <= 'Z') - c += 'a' - 'A'; - bool alnum = (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9'); - if (alnum) { - result += QLatin1Char(c); - begun = true; - dashAppended = false; - lastAlnum = result.size(); - } - else if (!dashAppended) { - if (begun) - result += QLatin1Char('-'); - dashAppended = true; - } - } - result.truncate(lastAlnum); - return result; -} - -void Doc::detach() -{ - if (!priv) { - priv = new DocPrivate; - return; - } - if (priv->count == 1) - return; - - --priv->count; - - DocPrivate *newPriv = new DocPrivate(*priv); - newPriv->count = 1; - if (priv->extra) - newPriv->extra = new DocPrivateExtra(*priv->extra); - - priv = newPriv; -} - -/*! - The destructor deletes all the sub-TopicRefs. - */ -TopicRef::~TopicRef() -{ - foreach (DitaRef* t, subrefs_) { - delete t; - } -} - -/*! - Returns a reference to the structure that will be used - for generating a DITA mao. - */ -const DitaRefList& Doc::ditamap() const { return priv->ditamap_; } - -QT_END_NAMESPACE diff --git a/src/tools/qdoc/doc.h b/src/tools/qdoc/doc.h deleted file mode 100644 index b064b5878e..0000000000 --- a/src/tools/qdoc/doc.h +++ /dev/null @@ -1,196 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/* - doc.h -*/ - -#ifndef DOC_H -#define DOC_H - -#include <qset.h> -#include <qstring.h> -#include <qmap.h> - -#include "location.h" - -QT_BEGIN_NAMESPACE - -class Atom; -class CodeMarker; -class Config; -class DocPrivate; -class Quoter; -class Text; -class DitaRef; - -typedef QPair<QString, Location> ArgLocPair; -typedef QList<ArgLocPair> ArgList; -typedef QMap<QString, QString> QStringMap; -typedef QMultiMap<QString, QString> QStringMultiMap; - -struct Topic -{ - QString topic; - QString args; - Topic() { } - Topic(QString& t, const QString &a) : topic(t), args(a) { } - bool isEmpty() const { return topic.isEmpty(); } - void clear() { topic.clear(); args.clear(); } -}; -typedef QList<Topic> TopicList; - -typedef QList<DitaRef*> DitaRefList; - -class DitaRef -{ -public: - DitaRef() { } - virtual ~DitaRef() { } - - const QString& navtitle() const { return navtitle_; } - const QString& href() const { return href_; } - void setNavtitle(const QString& t) { navtitle_ = t; } - void setHref(const QString& t) { href_ = t; } - virtual bool isMapRef() const = 0; - virtual const DitaRefList* subrefs() const { return 0; } - virtual void appendSubref(DitaRef* ) { } - -private: - QString navtitle_; - QString href_; -}; - -class TopicRef : public DitaRef -{ -public: - TopicRef() { } - ~TopicRef(); - - virtual bool isMapRef() const Q_DECL_OVERRIDE { return false; } - virtual const DitaRefList* subrefs() const Q_DECL_OVERRIDE { return &subrefs_; } - virtual void appendSubref(DitaRef* t) Q_DECL_OVERRIDE { subrefs_.append(t); } - -private: - DitaRefList subrefs_; -}; - -class MapRef : public DitaRef -{ -public: - MapRef() { } - ~MapRef() { } - - virtual bool isMapRef() const Q_DECL_OVERRIDE { return true; } -}; - -class Doc -{ - Q_DECLARE_TR_FUNCTIONS(QDoc::Doc) - -public: - // the order is important - enum Sections { - NoSection = -2, - Part = -1, - Chapter = 1, - Section1 = 1, - Section2 = 2, - Section3 = 3, - Section4 = 4 - }; - - Doc() : priv(0) {} - Doc(const Location& start_loc, - const Location& end_loc, - const QString& source, - const QSet<QString>& metaCommandSet, - const QSet<QString>& topics); - Doc(const Doc &doc); - ~Doc(); - - Doc& operator=( const Doc& doc ); - - void renameParameters(const QStringList &oldNames, - const QStringList &newNames); - void simplifyEnumDoc(); - void setBody(const Text &body); - const DitaRefList& ditamap() const; - - const Location &location() const; - const Location& startLocation() const; - const Location& endLocation() const; - bool isEmpty() const; - const QString& source() const; - const Text& body() const; - Text briefText(bool inclusive = false) const; - Text trimmedBriefText(const QString &className) const; - Text legaleseText() const; - Sections granularity() const; - const QSet<QString> ¶meterNames() const; - const QStringList &enumItemNames() const; - const QStringList &omitEnumItemNames() const; - const QSet<QString> &metaCommandsUsed() const; - const TopicList& topicsUsed() const; - ArgList metaCommandArgs(const QString& metaCommand) const; - const QList<Text> &alsoList() const; - bool hasTableOfContents() const; - bool hasKeywords() const; - bool hasTargets() const; - const QList<Atom *> &tableOfContents() const; - const QVector<int> &tableOfContentsLevels() const; - const QList<Atom *> &keywords() const; - const QList<Atom *> &targets() const; - const QStringMultiMap &metaTagMap() const; - - static void initialize( const Config &config ); - static void terminate(); - static QString alias( const QString &english ); - static void trimCStyleComment( Location& location, QString& str ); - static CodeMarker *quoteFromFile(const Location &location, - Quoter "er, - const QString &fileName); - static QString canonicalTitle(const QString &title); - static const Config* config() { return config_; } - -private: - void detach(); - DocPrivate *priv; - static const Config* config_; -}; -Q_DECLARE_TYPEINFO(Doc, Q_MOVABLE_TYPE); -typedef QList<Doc> DocList; - -QT_END_NAMESPACE - -#endif diff --git a/src/tools/qdoc/doc/config/qdoc.qdocconf b/src/tools/qdoc/doc/config/qdoc.qdocconf deleted file mode 100644 index 9d841e9b64..0000000000 --- a/src/tools/qdoc/doc/config/qdoc.qdocconf +++ /dev/null @@ -1,72 +0,0 @@ -include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) - -project = QDoc -description = QDoc Manual -version = $QT_VERSION - -sourcedirs = .. - -exampledirs = .. \ - ../examples - -imagedirs = ../images \ - ../../../../widgets/doc/images -# ../../../doc/src/templates/images - -tagfile = ../html/qdoc.tags - -examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml *.css *.qdoc *.qdocinc *.sample" - -qhp.projects = QDoc - -qhp.QDoc.file = qdoc.qhp -qhp.QDoc.namespace = org.qt-project.qdoc.$QT_VERSION_TAG -qhp.QDoc.virtualFolder = qdoc -qhp.QDoc.indexTitle = QDoc Manual -qhp.QDoc.indexRoot = - -qhp.QDoc.filterAttributes = qdoc qtrefdoc -qhp.QDoc.customFilters.QDoc.name = QDoc -qhp.QDoc.customFilters.QDoc.filterAttributes = qdoc -qhp.QDoc.subprojects = overviews -qhp.QDoc.subprojects.overviews.title = Overviews -qhp.QDoc.subprojects.overviews.indexTitle = QDoc Manual -qhp.QDoc.subprojects.overviews.selectors = fake:page,group,module - -depends += \ - activeqt \ - qtassistant \ - qtbluetooth \ - qtconcurrent \ - qtcontacts \ - qtcore \ - qtdbus \ - qtdesigner \ - qtdoc \ - qthelp \ - qtimageformats \ - qtgui \ - qtlocation \ - qtlinguist \ - qtmultimedia \ - qtnetwork \ - qtopengl \ - qtorganizer \ - qtprintsupport \ - qtqml \ - qtquick \ - qtscript \ - qtscripttools \ - qtsensors \ - qtsql \ - qtsvg \ - qttestlib \ - qtuitools \ - qtversit \ - qtwidgets \ - qtwebkit \ - qtwebkitexamples \ - qtxml \ - qtxmlpatterns - -navigation.landingpage = "QDoc Manual" diff --git a/src/tools/qdoc/doc/corefeatures.qdoc b/src/tools/qdoc/doc/corefeatures.qdoc deleted file mode 100644 index bbee7410fe..0000000000 --- a/src/tools/qdoc/doc/corefeatures.qdoc +++ /dev/null @@ -1,35 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page corefeatures.html - \title Core Features - - \input examples/signalandslots.qdocinc - \input examples/objectmodel.qdocinc - \input examples/layoutmanagement.qdocinc -*/ diff --git a/src/tools/qdoc/doc/examples/componentset/ProgressBar.qml b/src/tools/qdoc/doc/examples/componentset/ProgressBar.qml deleted file mode 100644 index c4e8c103e9..0000000000 --- a/src/tools/qdoc/doc/examples/componentset/ProgressBar.qml +++ /dev/null @@ -1,135 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the examples of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -/*! - \qmltype ProgressBar - \inqmlmodule UIComponents - \brief A component that shows the progress of an event - - A ProgressBar shows the linear progress of an event as its \l value. - The range is specified using the \l {minimum} and the \l{maximum} values. - - The ProgressBar component is part of the \l {UI Components} module. - - This documentation is part of the \l{componentset}{UIComponents} example. -*/ -Item { - id: progressbar - - /*! - The minimum value of the ProgressBar range. - The \l value must not be less than this value. - */ - property int minimum: 0 - - /*! - The maximum value of the ProgressBar range. - The \l value must not be more than this value. - */ - property int maximum: 100 - - /*! - The value of the progress. - */ - property int value: 0 - - /*! - \qmlproperty color ProgressBar::color - The color of the ProgressBar's gradient. Must bind to a color type. - - \omit - The "\qmlproperty <type> <property name>" is needed because - property alias need to have their types manually entered. - - QDoc will not publish the documentation within omit and endomit. - \endomit - - \sa secondColor - */ - property alias color: gradient1.color - - /*! - \qmlproperty color ProgressBar::secondColor - The second color of the ProgressBar's gradient. - Must bind to a color type. - - \omit - The "\qmlproperty <type> <property name>" is needed because - property alias need to have their types manually entered. - - QDoc will not publish the documentation within omit and endomit. - \endomit - - \sa color - */ - property alias secondColor: gradient2.color - - width: 250; height: 23 - clip: true - - Rectangle { - id: highlight - - /*! - An internal documentation comment. The widthDest property is not - a public API and therefore will not be exposed. - */ - property int widthDest: ((progressbar.width * (value - minimum)) / (maximum - minimum) - 6) - - width: highlight.widthDest - Behavior on width { SmoothedAnimation { velocity: 1200 } } - - anchors { left: parent.left; top: parent.top; bottom: parent.bottom; margins: 3 } - radius: 1 - gradient: Gradient { - GradientStop { id: gradient1; position: 0.0 } - GradientStop { id: gradient2; position: 1.0 } - } - - } - Text { - anchors { right: highlight.right; rightMargin: 6; verticalCenter: parent.verticalCenter } - color: "white" - font.bold: true - text: Math.floor((value - minimum) / (maximum - minimum) * 100) + '%' - } -} diff --git a/src/tools/qdoc/doc/examples/componentset/Switch.qml b/src/tools/qdoc/doc/examples/componentset/Switch.qml deleted file mode 100644 index 7b7e7af31f..0000000000 --- a/src/tools/qdoc/doc/examples/componentset/Switch.qml +++ /dev/null @@ -1,142 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the examples of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -/*! - \qmltype ToggleSwitch - \inqmlmodule UIComponents - \brief A component that can be turned on or off - - A toggle switch has two states: an \c on and an \c off state. The \c off - state is when the \l on property is set to \c false. - - The ToggleSwitch component is part of the \l {UI Components} module. - - This documentation is part of the \l{componentset}{UIComponents} example. - -*/ -Item { - id: toggleswitch - width: background.width; height: background.height - - /*! - Indicates the state of the switch. If \c false, then the switch is in - the \c off state. - - \omit - The \qmlproperty <type> <propertyname> is not necessary as QDoc - will associate this property to the ToggleSwitch - - QDoc will not publish the documentation within omit and endomit. - \endomit - */ - property bool on: false - - - /*! - A method to toggle the switch. If the switch is \c on, the toggling it - will turn it \c off. Toggling a switch in the \c off position will - turn it \c on. - */ - function toggle() { - if (toggleswitch.state == "on") - toggleswitch.state = "off"; - else - toggleswitch.state = "on"; - } - - - /*! - \internal - - An internal function to synchronize the switch's internals. This - function is not for public access. The \internal command will - prevent QDoc from publishing this comment in the public API. - */ - function releaseSwitch() { - if (knob.x == 1) { - if (toggleswitch.state == "off") return; - } - if (knob.x == 78) { - if (toggleswitch.state == "on") return; - } - toggle(); - } - - Rectangle { - id: background - width: 130; height: 48 - radius: 48 - color: "lightsteelblue" - MouseArea { anchors.fill: parent; onClicked: toggle() } - } - - Rectangle { - id: knob - width: 48; height: 48 - radius: width - color: "lightblue" - - MouseArea { - anchors.fill: parent - drag.target: knob; drag.axis: Drag.XAxis; drag.minimumX: 1; drag.maximumX: 78 - onClicked: toggle() - onReleased: releaseSwitch() - } - } - - states: [ - State { - name: "on" - PropertyChanges { target: knob; x: 78 } - PropertyChanges { target: toggleswitch; on: true } - }, - State { - name: "off" - PropertyChanges { target: knob; x: 1 } - PropertyChanges { target: toggleswitch; on: false } - } - ] - - transitions: Transition { - NumberAnimation { properties: "x"; easing.type: Easing.InOutQuad; duration: 200 } - } -} diff --git a/src/tools/qdoc/doc/examples/componentset/TabWidget.qml b/src/tools/qdoc/doc/examples/componentset/TabWidget.qml deleted file mode 100644 index 008c5e14e7..0000000000 --- a/src/tools/qdoc/doc/examples/componentset/TabWidget.qml +++ /dev/null @@ -1,183 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the examples of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** You may use this file under the terms of the BSD license as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -import QtQuick 1.0 - -/*! - \qmltype TabWidget - \inqmlmodule UIComponents - \brief A widget that places its children as tabs - - A TabWidget places its children as tabs in a view. Selecting - a tab involves selecting the tab at the top. - - The TabWidget component is part of the \l {UI Components} module. - - This documentation is part of the \l{componentset}{UIComponents} example. - - \section1 Adding Tabs - - To add a tab, declare the tab as a child of the TabWidget. - - \code - TabWidget { - id: tabwidget - - Rectangle { - id: tab1 - color: "red" - //... omitted - } - Rectangle { - id: tab2 - color: "blue" - //... omitted - } - - } - \endcode - -*/ -Item { - id: tabWidget - - /*! - \internal - - Setting the default property to stack.children means any child items - of the TabWidget are actually added to the 'stack' item's children. - - See the \l{"Property Binding in QML"} - documentation for details on default properties. - - This is an implementation detail, not meant for public knowledge. Putting - the \internal command at the beginning will cause QDoc to not publish this - documentation in the public API page. - - Normally, a property alias needs to have a - "\qmlproperty <type> <propertyname>" to assign the alias a type. - - */ - default property alias content: stack.children - - - /*! - The currently active tab in the TabWidget. - */ - property int current: 0 - - /*! - A sample \c{read-only} property. - A contrived property to demonstrate QDoc's ability to detect - read-only properties. - - The signature is: - \code - readonly property int sampleReadOnlyProperty: 0 - \endcode - - Note that the property must be initialized to a value. - - */ - readonly property int sampleReadOnlyProperty: 0 - - /*! - \internal - - This handler is an implementation - detail. The \c{\internal} command will prevent QDoc from publishing this - documentation on the public API. - */ - onCurrentChanged: setOpacities() - Component.onCompleted: setOpacities() - - /*! - \internal - - An internal function to set the opacity. - The \internal command will prevent QDoc from publishing this - documentation on the public API. - */ - function setOpacities() { - for (var i = 0; i < stack.children.length; ++i) { - stack.children[i].opacity = (i == current ? 1 : 0) - } - } - - Row { - id: header - - Repeater { - model: stack.children.length - delegate: Rectangle { - width: tabWidget.width / stack.children.length; height: 36 - - Rectangle { - width: parent.width; height: 1 - anchors { bottom: parent.bottom; bottomMargin: 1 } - color: "#acb2c2" - } - BorderImage { - anchors { fill: parent; leftMargin: 2; topMargin: 5; rightMargin: 1 } - border { left: 7; right: 7 } - source: "tab.png" - visible: tabWidget.current == index - } - Text { - horizontalAlignment: Qt.AlignHCenter; verticalAlignment: Qt.AlignVCenter - anchors.fill: parent - text: stack.children[index].title - elide: Text.ElideRight - font.bold: tabWidget.current == index - } - MouseArea { - anchors.fill: parent - onClicked: tabWidget.current = index - } - } - } - } - - Item { - id: stack - width: tabWidget.width - anchors.top: header.bottom; anchors.bottom: tabWidget.bottom - } -} diff --git a/src/tools/qdoc/doc/examples/componentset/componentset.pro b/src/tools/qdoc/doc/examples/componentset/componentset.pro deleted file mode 100644 index 5b44737c2d..0000000000 --- a/src/tools/qdoc/doc/examples/componentset/componentset.pro +++ /dev/null @@ -1,5 +0,0 @@ -SOURCES = componentset.pro \ - ProgressBar.qml \ - Switch.qml \ - TabWidget.qml \ - uicomponents.qdoc diff --git a/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample b/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample deleted file mode 100644 index 7a14f88f45..0000000000 --- a/src/tools/qdoc/doc/examples/componentset/uicomponents.qdoc.sample +++ /dev/null @@ -1,38 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \qmlmodule UIComponents 1.0 - \title UI Components - \brief Basic set of UI components - - This is a listing of a list of UI components implemented by QML types. These - files are available for general import and they are based off the \l{Qt - Quick Code Samples}. - - This module is part of the \l{componentset}{UIComponents} example. -*/ diff --git a/src/tools/qdoc/doc/examples/cpp.qdoc.sample b/src/tools/qdoc/doc/examples/cpp.qdoc.sample deleted file mode 100644 index 38a131783b..0000000000 --- a/src/tools/qdoc/doc/examples/cpp.qdoc.sample +++ /dev/null @@ -1,126 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//![class] -/*! - \class QCache - \brief The QCache class is a template class that provides a cache. - - \ingroup tools - \ingroup shared - - \reentrant - - QCache\<Key, T\> defines a cache that stores objects of type T - associated with keys of type Key. For example, here's the - definition of a cache that stores objects of type Employee - associated with an integer key: - - \snippet code/doc_src_qcache.cpp 0 - - Here's how to insert an object in the cache: - - \snippet code/doc_src_qcache.cpp 1 - - ... detailed description ommitted - - \sa QPixmapCache, QHash, QMap -*/ -//![class] - -//![function] -/*! - \fn QString &QString::remove(int position, int n) - - Removes \a n characters from the string, starting at the given \a - position index, and returns a reference to the string. - - If the specified \a position index is within the string, but \a - position + \a n is beyond the end of the string, the string is - truncated at the specified \a position. - - \snippet qstring/main.cpp 37 - - \sa insert(), replace() -*/ -QString &QString::remove(int pos, int len) -//! [function] - -//! [return] -/*! - Returns \c true if a QScroller object was already created for \a target; \c false otherwise. - - \sa scroller() -*/ -bool QScroller::hasScroller(QObject *target) -//! [return] - -//! [property] -/*! - \property QVariantAnimation::duration - \brief the duration of the animation - - This property describes the duration in milliseconds of the - animation. The default duration is 250 milliseconds. - - \sa QAbstractAnimation::duration() - */ -int QVariantAnimation::duration() const -//! [property] - -//! [signals] -/*! - \fn QAbstractTransition::triggered() - - This signal is emitted when the transition has been triggered (after - onTransition() has been called). -*/ -//! [signals] - -//! [enums] -/*! - \enum QSql::TableType - - This enum type describes types of SQL tables. - - \value Tables All the tables visible to the user. - \value SystemTables Internal tables used by the database. - \value Views All the views visible to the user. - \value AllTables All of the above. -*/ -//! [enums] - -//! [overloaded notifier] -/*! -\property QSpinBox::value -\brief the value of the spin box - -setValue() will emit valueChanged() if the new value is different -from the old one. The \l{QSpinBox::}{value} property has a second notifier -signal which includes the spin box's prefix and suffix. -*/ -//! [overloaded notifier] diff --git a/src/tools/qdoc/doc/examples/examples.qdoc b/src/tools/qdoc/doc/examples/examples.qdoc deleted file mode 100644 index 28810e30da..0000000000 --- a/src/tools/qdoc/doc/examples/examples.qdoc +++ /dev/null @@ -1,97 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example componentset - \title QML Documentation Example - - This example demonstrates one of the ways to document QML types. - - In particular, there are sample types that are documented with QDoc - commands comments. There are documentation comments for the QML types - and their public interfaces. The types are grouped into a module, the - \l{UI Components} module. - - The \l{componentset/uicomponents.qdoc.sample}{uicomponents.qdoc} file generates - the overview page for the \l{UI Components} module page. - - The generated documentation is available in the \l{UI Components} module. - - \section1 QML Class - - The QML types use the \l{qmltype-command}{\\qmltype} to document the - type. In addition, they have the \l{inmodule-command}{\\inmodule} - command in order for QDoc to associate them to the \c UIComponents module. - - QDoc uses the \l{brief-command}{\\brief} command to place a basic - description when listing the types. - - \section1 Properties, Signals, Handlers, and Methods - - The types have their properties, signals, handlers, and methods - defined in their respective QML files. QDoc associates the properties and - methods to the types, therefore, you only need to place the - documentation above the property, method, or signal. - - To document the type of a \e {property alias}, you must use the - \l{qmlproperty-command}{\\qmlproperty} command to specify the data type. - - \code - \qmlproperty int anAliasedProperty - An aliased property of type int. - \endcode - - \section2 Internal Documentation - - You may declare that a documentation is for internal use by placing the - \l{internal-command}{\\internal} command after the beginning QDoc comment - \begincomment. QDoc will prevent the internal documentation from appearing - in the public API. - - If you wish to omit certain parts of the documentation, you may use the - \l{omit-command}{\\omit} and \l{omit-command}{\\endomit} command. - - \section1 QML Types with C++ Implementation - - This example only demonstrates the documentation for types in QML - files, but the regular \l{qml-documentation}{QML commands} may be placed - inside C++ classes to define the public API of the QML type. - -*/ - - -/*! - \qmlmodule UIComponents 1.0 - \title UI Components - \brief Basic set of UI components - - This is a listing of a list of UI components implemented by QML types. These - files are available for general import and they are based on the - \l{Qt Quick Examples and Tutorials}{Qt Quick Code Samples}. - - This module is part of the \l{componentset}{UIComponents} example. -*/ diff --git a/src/tools/qdoc/doc/examples/layoutmanagement.qdocinc b/src/tools/qdoc/doc/examples/layoutmanagement.qdocinc deleted file mode 100644 index 780b03c8ff..0000000000 --- a/src/tools/qdoc/doc/examples/layoutmanagement.qdocinc +++ /dev/null @@ -1,13 +0,0 @@ -\section1 Layout Classes - -The Qt layout system provides a simple and powerful way of specifying -the layout of child widgets. - -By specifying the logical layout once, you get the following benefits: - -\list - \li Positioning of child widgets. - \li Sensible default sizes for windows. - \li Sensible minimum sizes for windows. - \li ... -\endlist diff --git a/src/tools/qdoc/doc/examples/main.cpp b/src/tools/qdoc/doc/examples/main.cpp deleted file mode 100644 index 849405e0ae..0000000000 --- a/src/tools/qdoc/doc/examples/main.cpp +++ /dev/null @@ -1,46 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include <QApplication> -#include <QPushButton> - -int main(int argc, char *argv[]) -{ - QApplication app(argc, argv); - - QPushButton hello("Hello world!"); - hello.resize(100, 30); - - hello.show(); - return app.exec(); -} diff --git a/src/tools/qdoc/doc/examples/mainwindow.cpp b/src/tools/qdoc/doc/examples/mainwindow.cpp deleted file mode 100644 index 68b878c07e..0000000000 --- a/src/tools/qdoc/doc/examples/mainwindow.cpp +++ /dev/null @@ -1,243 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the tools applications of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL21$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 or version 3 as published by the Free -** Software Foundation and appearing in the file LICENSE.LGPLv21 and -** LICENSE.LGPLv3 included in the packaging of this file. Please review the -** following information to ensure the GNU Lesser General Public License -** requirements will be met: https://www.gnu.org/licenses/lgpl.html and -** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** As a special exception, The Qt Company gives you certain additional -** rights. These rights are described in The Qt Company LGPL Exception -** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -#include <QtWidgets> - -#include "mainwindow.h" -#include "scribblearea.h" - -//! [0] -MainWindow::MainWindow() -{ - scribbleArea = new ScribbleArea; - setCentralWidget(scribbleArea); - - createActions(); - createMenus(); - - setWindowTitle(tr("Scribble")); - resize(500, 500); -} -//! [0] - -//! [1] -void MainWindow::closeEvent(QCloseEvent *event) -//! [1] //! [2] -{ - if (maybeSave()) { - event->accept(); - } else { - event->ignore(); - } -} -//! [2] - -//! [3] -void MainWindow::open() -//! [3] //! [4] -{ - if (maybeSave()) { - QString fileName = QFileDialog::getOpenFileName(this, - tr("Open File"), QDir::currentPath()); - if (!fileName.isEmpty()) - scribbleArea->openImage(fileName); - } -} -//! [4] - -//! [5] -void MainWindow::save() -//! [5] //! [6] -{ - QAction *action = qobject_cast<QAction *>(sender()); - QByteArray fileFormat = action->data().toByteArray(); - saveFile(fileFormat); -} -//! [6] - -//! [7] -void MainWindow::penColor() -//! [7] //! [8] -{ - QColor newColor = QColorDialog::getColor(scribbleArea->penColor()); - if (newColor.isValid()) - scribbleArea->setPenColor(newColor); -} -//! [8] - -//! [9] -void MainWindow::penWidth() -//! [9] //! [10] -{ - bool ok; - int newWidth = QInputDialog::getInteger(this, tr("Scribble"), - tr("Select pen width:"), - scribbleArea->penWidth(), - 1, 50, 1, &ok); - if (ok) - scribbleArea->setPenWidth(newWidth); -} -//! [10] - -//! [11] -void MainWindow::about() -//! [11] //! [12] -{ - QMessageBox::about(this, tr("About Scribble"), - tr("<p>The <b>Scribble</b> example shows how to use QMainWindow as the " - "base widget for an application, and how to reimplement some of " - "QWidget's event handlers to receive the events generated for " - "the application's widgets:</p><p> We reimplement the mouse event " - "handlers to facilitate drawing, the paint event handler to " - "update the application and the resize event handler to optimize " - "the application's appearance. In addition we reimplement the " - "close event handler to intercept the close events before " - "terminating the application.</p><p> The example also demonstrates " - "how to use QPainter to draw an image in real time, as well as " - "to repaint widgets.</p>")); -} -//! [12] - -//! [13] -void MainWindow::createActions() -//! [13] //! [14] -{ - openAct = new QAction(tr("&Open..."), this); - openAct->setShortcuts(QKeySequence::Open); - connect(openAct, SIGNAL(triggered()), this, SLOT(open())); - - foreach (const QByteArray &format, QImageWriter::supportedImageFormats()) { - QString text = tr("%1...").arg(QString(format).toUpper()); - - QAction *action = new QAction(text, this); - action->setData(format); - connect(action, SIGNAL(triggered()), this, SLOT(save())); - saveAsActs.append(action); - } - - printAct = new QAction(tr("&Print..."), this); - connect(printAct, SIGNAL(triggered()), scribbleArea, SLOT(print())); - - exitAct = new QAction(tr("E&xit"), this); - exitAct->setShortcuts(QKeySequence::Quit); - connect(exitAct, SIGNAL(triggered()), this, SLOT(close())); - - penColorAct = new QAction(tr("&Pen Color..."), this); - connect(penColorAct, SIGNAL(triggered()), this, SLOT(penColor())); - - penWidthAct = new QAction(tr("Pen &Width..."), this); - connect(penWidthAct, SIGNAL(triggered()), this, SLOT(penWidth())); - - clearScreenAct = new QAction(tr("&Clear Screen"), this); - clearScreenAct->setShortcut(tr("Ctrl+L")); - connect(clearScreenAct, SIGNAL(triggered()), - scribbleArea, SLOT(clearImage())); - - aboutAct = new QAction(tr("&About"), this); - connect(aboutAct, SIGNAL(triggered()), this, SLOT(about())); - - aboutQtAct = new QAction(tr("About &Qt"), this); - connect(aboutQtAct, SIGNAL(triggered()), qApp, SLOT(aboutQt())); -} -//! [14] - -//! [15] -void MainWindow::createMenus() -//! [15] //! [16] -{ - saveAsMenu = new QMenu(tr("&Save As"), this); - foreach (QAction *action, saveAsActs) - saveAsMenu->addAction(action); - - fileMenu = new QMenu(tr("&File"), this); - fileMenu->addAction(openAct); - fileMenu->addMenu(saveAsMenu); - fileMenu->addAction(printAct); - fileMenu->addSeparator(); - fileMenu->addAction(exitAct); - - optionMenu = new QMenu(tr("&Options"), this); - optionMenu->addAction(penColorAct); - optionMenu->addAction(penWidthAct); - optionMenu->addSeparator(); - optionMenu->addAction(clearScreenAct); - - helpMenu = new QMenu(tr("&Help"), this); - helpMenu->addAction(aboutAct); - helpMenu->addAction(aboutQtAct); - - menuBar()->addMenu(fileMenu); - menuBar()->addMenu(optionMenu); - menuBar()->addMenu(helpMenu); -} -//! [16] - -//! [17] -bool MainWindow::maybeSave() -//! [17] //! [18] -{ - if (scribbleArea->isModified()) { - QMessageBox::StandardButton ret; - ret = QMessageBox::warning(this, tr("Scribble"), - tr("The image has been modified.\n" - "Do you want to save your changes?"), - QMessageBox::Save | QMessageBox::Discard - | QMessageBox::Cancel); - if (ret == QMessageBox::Save) { - return saveFile("png"); - } else if (ret == QMessageBox::Cancel) { - return false; - } - } - return true; -} -//! [18] - -//! [19] -bool MainWindow::saveFile(const QByteArray &fileFormat) -//! [19] //! [20] -{ - QString initialPath = QDir::currentPath() + "/untitled." + fileFormat; - - QString fileName = QFileDialog::getSaveFileName(this, tr("Save As"), - initialPath, - tr("%1 Files (*.%2);;All Files (*)") - .arg(QString(fileFormat.toUpper())) - .arg(QString(fileFormat))); - if (fileName.isEmpty()) { - return false; - } else { - return scribbleArea->saveImage(fileName, fileFormat); - } -} -//! [20] diff --git a/src/tools/qdoc/doc/examples/minimum.qdocconf b/src/tools/qdoc/doc/examples/minimum.qdocconf deleted file mode 100644 index e360685f1d..0000000000 --- a/src/tools/qdoc/doc/examples/minimum.qdocconf +++ /dev/null @@ -1,38 +0,0 @@ -# QDoc is a tool that constantly evolves to suit our needs, -# and there are some compatibility issues between old and new -# practices. For that reason, any QDoc configuration file needs to -# include compat.qdocconf. - -#include(compat.qdocconf) - - -# The outputdir variable specifies the directory -# where QDoc will put the generated documentation. - -outputdir = html - - -# The headerdirs variable specifies the directories -# containing the header files associated -# with the .cpp source files used in the documentation. - -headerdirs = . - - -# The sourcedirs variable specifies the -# directories containing the .cpp or .qdoc -# files used in the documentation. - -#sourcedirs = . - - -# The exampledirs variable specifies the directories containing -# the source code of the example files. - -exampledirs = . - - -# The imagedirs variable specifies the -# directories containing the images used in the documentation. - -imagedirs = ./images diff --git a/src/tools/qdoc/doc/examples/objectmodel.qdocinc b/src/tools/qdoc/doc/examples/objectmodel.qdocinc deleted file mode 100644 index 02b5991c4d..0000000000 --- a/src/tools/qdoc/doc/examples/objectmodel.qdocinc +++ /dev/null @@ -1,11 +0,0 @@ -\section1 Qt Object Model - -The standard C++ object model provides very efficient runtime support -for the object paradigm. But its static nature is inflexibile in -certain problem domains. Graphical user interface programming is a -domain that requires both runtime efficiency and a high level of -flexibility. Qt provides this, by combining the speed of C++ with the -flexibility of the Qt Object Model. - -... - diff --git a/src/tools/qdoc/doc/examples/qml.qdoc.sample b/src/tools/qdoc/doc/examples/qml.qdoc.sample deleted file mode 100644 index cacd912242..0000000000 --- a/src/tools/qdoc/doc/examples/qml.qdoc.sample +++ /dev/null @@ -1,116 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//![qmltype] - \qmltype TextEdit - \instantiates QQuickTextEdit - \inqmlmodule QtQuick - \ingroup qtquick-visual - \ingroup qtquick-input - \inherits Item - \brief Displays multiple lines of editable formatted text - - The TextEdit item displays a block of editable, formatted text. - - It can display both plain and rich text. For example: - - \qml - TextEdit { - width: 240 - text: "<b>Hello</b> <i>World!</i>" - font.family: "Helvetica" - font.pointSize: 20 - color: "blue" - focus: true - } - \endqml - - \image declarative-textedit.gif - - ... omitted detailed description - - \sa Text, TextInput, {examples/quick/text/textselection}{Text Selection example} -//![qmltype] - -//![function] -/* - \qmlmethod QtQuick2::ListModel::remove(int index, int count = 1) - - Deletes the content at \a index from the model. - - \sa clear() -*/ -void QQuickListModel::remove(QQmlV8Function *args) -//! [function] - -//! [return] -/* - Returns \c true if a QScroller object was already created for \a target; \c false otherwise. - - \sa scroller() -*/ -bool QScroller::hasScroller(QObject *target) -//! [return] - -//! [property] -/* - \property QVariantAnimation::duration - \brief the duration of the animation - - This property describes the duration in milliseconds of the - animation. The default duration is 250 milliseconds. - - \sa QAbstractAnimation::duration() - */ -int QVariantAnimation::duration() const -//! [property] - -//! [signals] -/* - This signal is emitted when the user clicks the button. A click is defined - as a press followed by a release. The corresponding handler is - \c onClicked. -*/ -signal clicked() -//! [signals] - -//! [enums] -/*! -\qmlproperty enumeration QtQuick2::Text::font.weight - -Sets the font's weight. - -The weight can be one of: -\list -\li Font.Light -\li Font.Normal - the default -\li Font.DemiBold -\li Font.Bold -\li Font.Black -\endlist -*/ -//! [enums] diff --git a/src/tools/qdoc/doc/examples/samples.qdocinc b/src/tools/qdoc/doc/examples/samples.qdocinc deleted file mode 100644 index d5679fdcd8..0000000000 --- a/src/tools/qdoc/doc/examples/samples.qdocinc +++ /dev/null @@ -1,109 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -//! [qvector3d-class] -/*! - \class QVector3D - \brief The QVector3D class represents a vector or vertex in 3D space. - \since 4.6 - \ingroup painting-3D - - Vectors are one of the main building blocks of 3D representation and - drawing. They consist of three coordinates, traditionally called - x, y, and z. - - The QVector3D class can also be used to represent vertices in 3D space. - We therefore do not need to provide a separate vertex class. - - \b{Note:} By design values in the QVector3D instance are stored as \c float. - This means that on platforms where the \c qreal arguments to QVector3D - functions are represented by \c double values, it is possible to - lose precision. - - \sa QVector2D, QVector4D, QQuaternion -*/ -//! [qvector3d-class] - -//! [qvector3d-function] -/*! - \fn QVector3D::QVector3D(const QPoint& point) - - Constructs a vector with x and y coordinates from a 2D \a point, and a - z coordinate of 0. -*/ -//! [qvector3d-function] - -//! [sample-page] -/*! - \page generic-guide.html - \title Generic QDoc Guide - \nextpage Creating QDoc Configuration Files - There are three essential materials for generating documentation with qdoc: - - \list - \li \c qdoc binary - \li \c qdocconf configuration files - \li \c Documentation in \c C++, \c QML, and \c .qdoc files - \endlist -*/ -//! [sample-page] - -//! [sample-faq] -/*! - \page altruism-faq.html faq - \title Altruism Frequently Asked Questions - - \brief All the questions about altruism, answered. - - ... -*/ -//! [sample-faq] - -//! [sample-example] -/*! - \title UI Components: Tab Widget Example - \example declarative/ui-components/tabwidget - - This example shows how to create a tab widget. It also demonstrates how - \l {Property aliases}{property aliases} and - \l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and - assemble the child items declared within an \l Item. - - \image qml-tabwidget-example.png -*/ -//! [sample-example] - -//! [sample-overview] -/*! - \page overview-qt-technology.html overview - \title Overview of a Qt Technology - - \brief provides a technology never seen before. - -*/ -//! [sample-overview] - diff --git a/src/tools/qdoc/doc/examples/signalandslots.qdocinc b/src/tools/qdoc/doc/examples/signalandslots.qdocinc deleted file mode 100644 index e14ede1441..0000000000 --- a/src/tools/qdoc/doc/examples/signalandslots.qdocinc +++ /dev/null @@ -1,9 +0,0 @@ -\section1 Signals and Slots - -Signals and slots are used for communication between objects. The signals and -slots mechanism is a central feature of Qt and probably the part that differs -most from the features provided by other frameworks. - -\section2 Introduction - -In GUI programming, when we ... diff --git a/src/tools/qdoc/doc/files/basicqt.qdoc.sample b/src/tools/qdoc/doc/files/basicqt.qdoc.sample deleted file mode 100644 index ce8df096fa..0000000000 --- a/src/tools/qdoc/doc/files/basicqt.qdoc.sample +++ /dev/null @@ -1,67 +0,0 @@ - /*! - \page basicqt.html - \contentspage {Basic Qt} {Contents} - \nextpage Getting Started - - \indexpage Index - \startpage Basic Qt - - \title Basic Qt - - The Qt toolkit is a C++ class library and a set of tools for - building multiplatform GUI programs using a "write once, - compile anywhere approach". - - Table of contents: - - \list - \li \l {Getting Started} - \li \l {Creating Dialogs} - \li \l {Creating Main Windows} - \endlist - */ - - /*! - \page gettingstarted.html - \previouspage Basic Qt - \contentspage {Basic Qt} {Contents} - \nextpage Creating Dialogs - - \indexpage Index - \startpage Basic Qt - - \title Getting Started - - This chapter shows how to combine basic C++ with the - functionality provided by Qt to create a few small graphical - interface (GUI) applications. -*/ - -/ *! - \page creatingdialogs.html - \previouspage Getting Started - \contentspage {Basic Qt} {Contents} - - \indexpage Index - \startpage Basic Qt - - \title Creating Dialogs - - This chapter will teach you how to create dialog boxes using Qt. -*/ - -/*! - \page index.html - - \indexpage Index - \startpage Basic Qt - - \title Index - - \list - \li \l {Basic Qt} - \li \l {Creating Dialogs} - \li \l {Getting Started} - \endlist -*/ - diff --git a/src/tools/qdoc/doc/files/compat.qdocconf b/src/tools/qdoc/doc/files/compat.qdocconf deleted file mode 100644 index 3e7ea6c891..0000000000 --- a/src/tools/qdoc/doc/files/compat.qdocconf +++ /dev/null @@ -1,12 +0,0 @@ -alias.include = input - -macro.0 = "\\\\0" -macro.b = "\\\\b" -macro.n = "\\\\n" -macro.r = "\\\\r" -macro.img = "\\image" -macro.endquote = "\\endquotation" -macro.relatesto = "\\relates" - -spurious = "Missing comma in .*" \ - "Missing pattern .*" diff --git a/src/tools/qdoc/doc/files/qtgui.qdocconf b/src/tools/qdoc/doc/files/qtgui.qdocconf deleted file mode 100644 index 0b2d281081..0000000000 --- a/src/tools/qdoc/doc/files/qtgui.qdocconf +++ /dev/null @@ -1,49 +0,0 @@ -include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) - -project = QtGui -description = Qt GUI Reference Documentation -version = $QT_VERSION - -examplesinstallpath = qtbase/gui - -qhp.projects = QtGui - -qhp.QtGui.file = qtgui.qhp -qhp.QtGui.namespace = org.qt-project.qtgui.$QT_VERSION_TAG -qhp.QtGui.virtualFolder = qtgui -qhp.QtGui.indexTitle = Qt GUI -qhp.QtGui.indexRoot = - -qhp.QtGui.filterAttributes = qtgui $QT_VERSION qtrefdoc -qhp.QtGui.customFilters.Qt.name = Qtgui $QT_VERSION -qhp.QtGui.customFilters.Qt.filterAttributes = qtgui $QT_VERSION - -qhp.QtGui.subprojects = classes -qhp.QtGui.subprojects.classes.title = C++ Classes -qhp.QtGui.subprojects.classes.indexTitle = Qt GUI C++ Classes -qhp.QtGui.subprojects.classes.selectors = class fake:headerfile -qhp.QtGui.subprojects.classes.sortPages = true - -tagfile = ../../../doc/qtgui/qtgui.tags - -depends += \ - qtcore \ - qtnetwork \ - qtopengl \ - qtsvg \ - qtqml \ - qtquick \ - qtwidgets \ - qtdoc - -headerdirs += .. - -sourcedirs += .. \ - ../../../examples/gui/doc/src - -exampledirs += ../../../examples/gui \ - snippets - -imagedirs += images \ - ../../../examples/gui/doc/images \ - ../../../doc/src/images \ diff --git a/src/tools/qdoc/doc/images/happy.gif b/src/tools/qdoc/doc/images/happy.gif Binary files differdeleted file mode 100644 index a4597f6fa8..0000000000 --- a/src/tools/qdoc/doc/images/happy.gif +++ /dev/null diff --git a/src/tools/qdoc/doc/images/happyguy.jpg b/src/tools/qdoc/doc/images/happyguy.jpg Binary files differdeleted file mode 100644 index e8604793c2..0000000000 --- a/src/tools/qdoc/doc/images/happyguy.jpg +++ /dev/null diff --git a/src/tools/qdoc/doc/images/link-to-qquickitem.png b/src/tools/qdoc/doc/images/link-to-qquickitem.png Binary files differdeleted file mode 100644 index 00e03c3717..0000000000 --- a/src/tools/qdoc/doc/images/link-to-qquickitem.png +++ /dev/null diff --git a/src/tools/qdoc/doc/images/links-to-broken-links.png b/src/tools/qdoc/doc/images/links-to-broken-links.png Binary files differdeleted file mode 100644 index 775143bd4a..0000000000 --- a/src/tools/qdoc/doc/images/links-to-broken-links.png +++ /dev/null diff --git a/src/tools/qdoc/doc/images/links-to-links.png b/src/tools/qdoc/doc/images/links-to-links.png Binary files differdeleted file mode 100644 index 9d2cc2fae5..0000000000 --- a/src/tools/qdoc/doc/images/links-to-links.png +++ /dev/null diff --git a/src/tools/qdoc/doc/images/qa-table.png b/src/tools/qdoc/doc/images/qa-table.png Binary files differdeleted file mode 100644 index 5818739fac..0000000000 --- a/src/tools/qdoc/doc/images/qa-table.png +++ /dev/null diff --git a/src/tools/qdoc/doc/images/qt-logo.png b/src/tools/qdoc/doc/images/qt-logo.png Binary files differdeleted file mode 100644 index 6b72d5fb72..0000000000 --- a/src/tools/qdoc/doc/images/qt-logo.png +++ /dev/null diff --git a/src/tools/qdoc/doc/images/training.jpg b/src/tools/qdoc/doc/images/training.jpg Binary files differdeleted file mode 100644 index c2ce5c3b21..0000000000 --- a/src/tools/qdoc/doc/images/training.jpg +++ /dev/null diff --git a/src/tools/qdoc/doc/qa-pages.qdoc b/src/tools/qdoc/doc/qa-pages.qdoc deleted file mode 100644 index a96673901a..0000000000 --- a/src/tools/qdoc/doc/qa-pages.qdoc +++ /dev/null @@ -1,109 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 28-qdoc-qa-pages.html - \previouspage Generating DITA XML Output - \contentspage QDoc Manual - \nextpage QDoc Manual - - \title QA Pages - - qdoc can generate some extra HTML pages that can be useful for - debugging qdoc documentation. These \e QA pages make it easier for - those who write documentation to find links that either go to the - wrong targets or don't go anywhere at all. - - \section2 Generating the QA Pages - - Add \c {-write-qa-pages} to the command line to tell qdoc to - generate the QA pages. If this option is not provided, the QA - pages will not be generated, and previolusly generated QA pages - will be deleted. - - \section2 Finding the Module's Main QA Page - - The main QA page for a module is not linked into the module's - generated documentation, but it is located in the same output - directory. To find the top-level QA page for module \e {xxx}, set - your browser to the qdoc output directory for module \e {xxx}. - Several files whose names begin with \e {aaa} appear at the top of - the list. These are the QA pages for module \e{xxx}. The file - names begin with \e {aaa} to ensure that they are easy to find at - the top of the directory. - - For module \e{xxx}, find the file \e{aaa-xxx-qa-page.html}. This - is the top-level QA page for module \e{xxx}. Load that file into - the browser. The top-level QA page shows a table that contains - links to several QA sub-pages. - - For example, the main QA page for QtCore is \c{aaa-qtcore-qa-page.html}. - This was the table for QtCore at one point: - - \image qa-table.png - - Each table entry shows the number of links from QtCore to some - other module, except for the last entry, which shows the number of - broken links in QtCore. Click the \b qtquick entry to load the QA - subpage showing the links from QtCore to QtQuick. - - \section2 Links To Links Page - - Clicking the \b qtquick table entry on the main QA page for QtCore - loads the QA subpage showing a table containing all the links from - QtCore to QtQuick. The table contains all the links constructed - with the \l {l-command} {\\l command}, as well as the autolinks. - - \image links-to-links.png - - At the time this table was generated, there were six links from - QtCore to QtQuick. The first column of each table entry contains - a link to some link in QtCore. The link text as it appears in - QtCore is shown. The second and third columns contain the source - file name and line number for where qdoc saw the link in a qdoc - comment. - - \note The line number will normally refer to the first line of the - comment where qdoc saw the link. - - Clicking on a link in the table takes you to that link in the - documentation. There the link will be marked with three red - asterisks. For example, clicking on the link in the fifth table - entry takes you here: - - \image link-to-qquickitem.png - - The link is marked with three red asterisks. Now you can click on - the actual link to check that it goes to the correct place. In - this case, the link should go to the reference page for the - QQuickItem class. You can check each link in the table this - way. If you find a link that goes to the wrong place, use the - source file name and line number to find the link, and fix the - problem using the square bracket notation for the \l {l-command} - {\\l command}. - - */ diff --git a/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc b/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc deleted file mode 100644 index af1fa1ba14..0000000000 --- a/src/tools/qdoc/doc/qdoc-guide/qdoc-guide.qdoc +++ /dev/null @@ -1,632 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ -/*! - \page qdoc-guide.html - \title Getting Started with QDoc - \nextpage Creating QDoc Configuration Files - - Qt uses QDoc to generate its documentation set into HTML and DITA XML - formats. QDoc uses a set of configuration files to generate documentation - from QDoc comments. The comments have types called - \l{writing-topic-commands}{topics} that determine whether a comment is a - class documentation or a property documentation. A comment may also have - \l{writing-markup}{mark up} to enhance the layout and formatting of the - final output. - - There are three essential materials for generating documentation with qdoc: - \list - \li \c QDoc binary - \li \c qdocconf configuration files - \li \c Documentation in \c C++, \c QML, and \c .qdoc files - \endlist - - This section intends to cover the basic necessities for creating a - documentation set. Additionally, the guide presents special considerations - and options to documenting non-C++ API documentation as well as QML - documentation. Finally, the guide will provide a sample project - documentation and an example of a QML type documentation. - - For specific QDoc information, consult the - \l{QDoc Manual}. - \section1 Chapters - - \list 1 - \li \l{Creating QDoc Configuration Files} - \li \l{Writing Documentation} - \li \l{Categories of Documentation} - \list - \li \l{C++ Documentation Style} - \li \l{QML Documentation Style} - \endlist - \li \l{QML Documentation Example} - \endlist - -*/ - -/*! - \page qdoc-guide-conf.html - \title Creating QDoc Configuration Files - \previouspage Getting Started with QDoc - \nextpage Writing Documentation - To generate documentation, QDoc uses configuration files, with the - \c qdocconf extension, to store configuration settings. - - The \l{The QDoc Configuration File} article covers the various configuration - variables in greater detail. - - \section1 QDoc Configuration Files - QDoc's configuration settings can reside in a single \e qdocconf file, but - can also be in other qdocconf files. The \c {include(<filepath>)} command - allows configuration files to include other configuration files. - - QDoc has two outputs, HTML documentation and documentation in DITA XML - format. The main distinction between the two outputs is that HTML - documentation needs to have its HTML styling information in the - configuration files. DITA XML documentation does not, and a separate process - can style the documentation in DITA at a later time. DITA XML is therefore - more flexible in allowing different styles to apply to the same information. - - To run qdoc, the project configuration file is supplied as an argument. - \code - qdoc project.qdocconf - \endcode - - The project configuration contains information that qdoc uses to create the - documentation. - - \section2 Project Information - - QDoc uses the \c project information to generate the documentation. - \code - project = QDoc Project - description = Sample QDoc project - \endcode - - \target qdoc-input-output-dir - \section2 Input and Output Directories - - Specifying the path to the source directories allow QDoc to find sources and - generate documentation. - - \badcode - sourcedirs = <path to source code> - exampledirs = <path to examples directory> - imagedirs = <path to image directory> - - sources.fileextensions = "*.cpp *.qdoc *.mm *.qml" - headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx" - examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml" - examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng" - \endcode - - QDoc will process headers and sources from the ones specified in the - \c fileextensions variable. - - Likewise, QDoc needs the path to the output directory. The \c outputformats - variable determines the type of documentation. These variables should be - in separate configuration files to modularize the documentation build. - \badcode - outputdir = $SAMPLE_PROJECT/doc/html - outputformats = HTML - \endcode - - QDoc can resolve the paths relative to the qdocconf file as well as - environment variables. - - \note During each QDoc run, the output directory is deleted. - \section2 Extra Files - - QDoc will output generated documentation into the directory specified in - the \l{Input and Output Directories}{output} directory. It is also possible - to specify extra files that QDoc should export. - - \badcode - HTML.extraimages = extraImage.png \ - extraImage2.png - \endcode - - The \c extraImage.png and the \c extraImage2.png files will be copied to the - HTML output directory. - - \section2 Qt Help Framework Configuration - - QDoc will also export a \e {Qt Help Project} file, in a \c qhp file. - The qhp file is then used by the \c qhelpgenerator to package the - documentation into a \c qch file. Qt Creator and Qt Assistant reads the qch - file to display the documentation. - - The \l {Creating Help Project Files} article covers the configuration - options. - - \section2 HTML Configuration - - QDoc has an HTML generator that will export a set of documentation into - HTML files using various configuration settings. QDoc will place the - generated documentation into the directory specified by the \c outputdir - variable. - - \badcode - outputformats = HTML - outputdir = <path to output directory> - \endcode - - QDoc needs to know where the styles and templates for generating HTML - are located. Typically, the templates directory contains a \c scripts, - \c images, and a \c style directory, containing scripts and CSS files. - - \badcode - HTML.templatedir = <path to templates> - \endcode - - The main configuration variables are: - \badcode - HTML.postheader - HTML.postpostheader - HTML.postheader - HTML.footer - - HTML.headerstyles - HTML.stylesheets = style.css \ - style1.css - - HTML.scripts = script.js - \endcode - - The \c{HTML.headerstyles} variable inserts the style information into the - HTML file and the \c{HTML.stylesheets} specifies which files QDoc should - copy into the output directory. As well, QDoc will embed the string - in the \c postheader, \c footer, and related variables into each HTML file. - - The \l {HTML Specific Configuration Variables} article outlines the usage - of each variable. - - \section2 DITA XML Configuration - - DITA XML output is enabled using the \c outputformats variable. Unlike HTML - documentation, QDoc does not need HTML style templates for generating - documentation in DITA XML format. - - \badcode - outputformats = DITAXML - outputdir - \endcode - - \section2 Qt Index Reference - Documentation projects can link to Qt APIs and other articles by specifying - the path to the \c qt.index file. When qdoc generates the Qt Reference - Documentation, it will also generate an index file, containing the URLs to - the articles. Other projects can use the links in the index file so that - they can link to other articles and API documentation within Qt. - - \badcode - indexes = $QT_INSTALL_DOCS/html/qt.index $OTHER_PROJECT/html/qt.index - \endcode - It is possible to specify multiple index files from several projects. - - \section1 Macros and Other Configurations - - Macros for substituting HTML characters exist and are helpful for generating - specific HTML-valid characters. - - \badcode - macro.pi.HTML = "Π" - \endcode - The snippet code will replace any instances of \c{\\pi} with \c Π in the - HTML file, which will appear as the Greek \pi symbol when viewed in - browsers. - - \section2 QML Additions - - QDoc is able to parse QML files for QDoc comments. QDoc will parse files - with the QML extension, \c{.qml}, if the extension type is included in the - \l{Input and Output Directories}{fileextensions} variable. - - Also, the generated HTML files can have a prefix and a suffix following the - QML module name, specified in the QDoc configuration file. - \badcode - outputprefixes = QML - outputprefixes.QML = uicomponents- - outputsuffixes = QML - outputsuffixes.QML = -tp - \endcode - - \b {See also}: \l {outputprefixes-variable}{outputprefixes}, - \l {outputsuffixes-variable}{outputsuffixes}. - -*/ - -/*! - \page qdoc-guide-writing.html - \title Writing Documentation - \previouspage Creating QDoc Configuration Files - \nextpage Categories of Documentation - - \section1 QDoc Comments - - Documentation is contained within qdoc \e comments, delimited by - \beginqdoc and \endqdoc comments. Note that these are valid comments - in C++, QML, and JavaScript. - - QDoc will parse C++ and QML files to look for qdoc comments. To explicitly - omit a certain file type, omit it from the - \l{Input and Output Directories}{configuration} file. - - \section1 QDoc Commands - - QDoc uses \e commands to retrieve information about the documentation. \c - Topic commands determine the type of documentation element, the \c context - commands provide hints and information about a topic, and \c markup commands - provide information on how QDoc should format a piece of documentation. - - \target writing-topic-commands - \section2 QDoc Topics - Each qdoc comment must have a \e topic type. A topic distinguishes it from - other topics. To specify a topic type, use one of the several - \l{Topic Commands}{topic commands}. - - QDoc will collect similar topics and create a page for each one. For - example, all the enumerations, properties, functions, and class description - of a particular C++ class will reside in one page. A generic page is - specified using the \l{page-command}{\\page} command and the filename is the - argument. - - Example of topic commands: - \list - \li \l{enum-command}{\\enum}Ā - for enumeration documentation - \li \l{class-command}{\\class} - for C++ class documentation - \li \l{qmltype-command}{\\qmltype} - for QML type documentation - \li \l{page-command}{\\page} - for creating a page. - \endlist - - The \l{page-command}{\\page} command is for creating articles that are not - part of source documentation. The command can also accept two arguments: the - file name of the article and the documentation type. The possible types are: - \list - \li \c howto - \li \c overview - \li \c tutorial - \li \c faq - \li \c article - \e default when there is no type - \endlist - - \snippet examples/samples.qdocinc sample-faq - - The \l{Topic Commands} page has information on all of the available topic - commands. - - \target writing-context - \section2 Topic Contexts - - Context commands give QDoc a hint about the \e context of the topic. For - example, if a C++ function is obsolete, then it should be marked obsolete - with the \l{obsolete-command}{\\obsolete} command. Likewise, - \l{nextpage-command}{page navigation} and \l{title-command}{page title}Ā - give extra page information to QDoc. - - QDoc will create additional links or pages for these contexts. For example, - a group is created using the \l{group-command}{\\group}Ā command and the - members have the \l{ingroup-command}{\\ingroup} command. The group name is - supplied as an argument. - - The \l{Context Commands}Ā page has a listing of all the available context - commands. - - \target writing-markup - \section2 Documentation Markup - - QDoc can do \e markup of text similar to other markup or - documentation tools. QDoc can mark a section of text in \b{bold}, - when the text is marked up with the \l{b-command}{\\b} command. - - \code - \b{This} text will be in \b{bold}. - \endcode - - The \l{Markup Commands} page has a full listing of the available markup - commands. - - \section1 Anatomy of Documentation - - Essentially, for QDoc to create a page, there must be some essential - ingredients present. - - \list - \li Assign a topic to a QDoc comment - A comment could be a page, a - property documentation, a class documentation, or any of the available - \l{Topic Commands}{topic commands}. - - \li Give the topic a context - QDoc can associate certain topics to other - pages such as associating obsolete functions when the documentation is - marked with \l{obsolete-command}{\\obsolete}. - - \li Mark sections of the document with - \l{Markup Commands}{markup commands} - QDoc can create layouts and - format the documentation for the documentation. - \endlist - - In Qt, the \l{QVector3D} class was documented with the following QDoc - comment: - \snippet examples/samples.qdocinc qvector3d-class - - It has a constructor, \l{QVector3D::QVector3D()}, which was documented with - the following QDoc comment: - \snippet examples/samples.qdocinc qvector3d-function - - The different comments may reside in different files and QDoc will collect - them depending on their topic and their context. The resulting documentation - from the snippets are generated into the \l{QVector3D} class documentation. - - Note that if the documentation immediately precedes the function or class - in the source code, then it does not need to have a topic. QDoc will assume - that the documentation above the code is the documentation for that code. - - An article is created using \l{page-command}{\\page} command. The first - argument is the HTML file that QDoc will create. The topic is supplemented - with context commands, the \l{title-command}{\\title} and - \l{nextpage-command}{\\nextpage} commands. There are several other - QDoc commands such as the \l{list-command}{\\list} command. - \snippet examples/samples.qdocinc sample-page - - The section on \l{QDoc Topics}{topic commands} gives an overview on several - other topic types. - - -*/ - -/*! - \page qdoc-categories.html - \title Categories of Documentation - \previouspage Writing Documentation - \nextpage QML Documentation Example - \brief Describes the different types such as How-To's, Tutorials, Overviews, - Examples, and Class Documentation. - - There are several types of predefined documentation \e categories or - \e types: - \list - \li How-To's - \li Tutorial - \li Overview - \li Article - \li FAQ (Frequently Asked Questions) - \li C++ API Documentation - \li QML Type Documentation - \li Code Example - \endlist - - QDoc has the ability to format a page depending on the type. Further, - stylesheets can provide additional control on the display of each category. - - \section1 API Documentation - QDoc excels in the creation of API documentation given a set of source code - and documentation in QDoc comments. Specifically, QDoc is aware of Qt's - architecture and can validate the existence of Qt C++ class, function, or - property documentation. QDoc gives warnings and errors if it cannot - associate a documentation with a code entity or if a code entity does not - have documentation. - - In general, every Qt code entity such as properties, classes, methods, - signals, and enumerations have a corresponding - \l{qdoc-topics}{topic command}. QDoc will associate the documentation to the - source using C++ naming rules. - - QDoc will parse the header files (typically \c .h files) to build a tree of - the class structures. Then QDoc will parse the source files and - documentation files to attach documentation to the class structure. - Afterwards, QDoc will generate a page for the class. - - \note QDoc uses the header files to inform itself about the class and will - not properly process QDoc comments in header files. - - \section2 Language Styles - - To produce quality API documentation, the Qt API references follow a - particular language guidelines. While the contents of this page demonstrates - how to create API documentation, the style guidelines demonstrate how - the reference materials follow a consistent use of language. - - \list - \li \l{C++ Documentation Style} - \li \l{QML Documentation Style} - \endlist - - \keyword qml-documentation - \section2 Documenting QML Types - - In the world of \l{Qt Quick}{QML}, there are additional entities we need to - document such as QML signals, attached properties, and QML methods. - Internally, they use Qt technologies, however, QML API documentation - requires different layout and naming conventions from the Qt C++ API - documentation. - - A list of QML related QDoc commands: - \list - \li \l{qmlattachedproperty-command}{\\qmlattachedproperty} - \li \l{qmlattachedsignal-command}{\\qmlattachedsignal} - \li \l{qmlbasictype-command}{\\qmlbasictype} - \li \l{qmltype-command}{\\qmltype} - creates a QML type documentation - \li \l{qmlmethod-command}{\\qmlmethod} - \li \l{qmlproperty-command}{\\qmlproperty} - \li \l{qmlsignal-command}{\\qmlsignal} - \li \l{inherits-command}{\\inherits} - \li \l{qmlmodule-command}{\\qmlmodule} - \li \l{inqmlmodule-command}{\\inqmlmodule} - \li \l{instantiates-command}{\\instantiates} - - \endlist - - \note Remember to enable QML parsing by including the \c{*.qml} filetype in - the \l{qdoc-input-output-dir}{fileextension} variable. - - To document a QML type, start by creating a QDoc comment that uses the - \l{qmltype-command} {\\qmltype} command as its topic command. - - \section3 QML Parser - - If your QML type is defined in a \e qml file, document it there. - If your QML type is represented by a C++ class, document it in the - \e cpp file for that C++ class and include an - \l{instantiates-command}{\\instantiates} command to specify the - name of the C++ class. Don't document a QML type in a \e{cpp} file - if the QML type is defined in a \e{qml} file. - - When documenting a QML type in a \e{qml} file, place each QDoc - comment directly above the entity to which the comment applies. - For example, place the QDoc comment containing the \e{\\qmltype} - command (the topic comment) directly above the outer QML type in - the \e{qml} file. Place the comment for documenting a QML property - directly above the property declaration, and so on for QML signal - handlers and QML methods. Note that when documenting QML - properties in a \e{qml} file, you don't normally include the - \e{\\qmlproperty} command as a topic command (which you must do - when documenting QML types in \e{cpp} files), because the QML - parser automatically associates each QDoc comment with the next - QML declaration it parses. The same is true for QML signal handler - and QML method comments. But it is sometimes useful to include one - or more \e{\\qmlproperty} commands in the comment, e.g. when the - property type is another QML type and you want the user to only - use certain properties within that other QML type, but not all of - them. But when documenting a property that has an alias, place the - QDoc comment for it directly above the alias declaration. In these - cases, the QDoc comment \e must contain a \e{\\qmlproperty} - command, because that is the only way QDoc can know the type of - the aliased property. - - When documenting a QML type in the \e cpp file of its - corresponding C++ class (if it has one), you normally place each - QDoc comment directly above the entity it documents. However, QDoc - does not use the QML parser to parse these files (the C++ parser - is used), so these QML QDoc comments can appear anywhere in the - \e{cpp} file. Note that QML QDoc comments in \e cpp files \e must - use the QML topic commands. i.e., the \l{qmltype-command} - {\\qmltype} command \e must appear in the QDoc comment for the - QML type, and a \l{qmlproperty-command} {\\qmlproperty} command \e - must appear in each QML property QDoc comment. - - \section3 QML Modules - - A QML type belongs to a \e module. The module - may include all the related types for a platform or contain a certain - version of \l{Qt Quick}. For example, the Qt Quick 2 QML types belong - to the Qt Quick 2 module while there is also a Qt Quick 1 module for the older - types introduced in Qt 4. - - QML modules allow grouping QML types. The \l{qmltype-command} - {\\qmltype} topic command must have an \l{inqmlmodule-command} - {\\inqmlmodule} context command to relate the type to a QML - module. Similarly, a \l{qmlmodule-command}{\\qmlmodule} topic - command must exist in a separate \c{.qdoc} file to create the - overview page for the module. The overview page will list the - QML types of the QML module. - - The links to the QML types must therefore also contain the module name. - For example, if a type called \c TabWidget is in the \c UIComponents - module, it must be linked as \c {UIComponents::TabWidget}. - - The \l{componentset}{UIComponents} example demonstrates proper usage of - QDoc commands to document QML types and QML modules. - - \section3 Read-only and Internal QML Properties - - QDoc detects QML properties that are marked as \c readonly. Note that the - property must be initialized with a value. - - \code - readonly property int sampleReadOnlyProperty: 0 - \endcode - For example, the example \l{TabWidget} type has a fictitious read-only - property \c sampleReadOnlyProperty. Its declaration has the \c readonly - identifier and it has an initial value. - - Properties and signals that are not meant for the public interface may - be marked with the \l{internal-command}{\\internal} command. QDoc will not - publish the documentation in the generated outputs. - - \section1 Articles & Overviews - Articles and overviews are a style of writing best used for providing - summary detail on a topic or concept. It may introduce a technology or - discuss how a concept may be applied, but without discussing exact steps - in too much detail. However, this type of content could provide the entry - point for readers to find instructional and reference materials that do, - such as tutorials, examples and class documentation. An example of an - overview might be a product page, such as a top level discussion of - Qt Quick, individual modules, design principles, or tools. - - To signify that a document is an article, you append the article keyword - to the \\page command: - - \snippet examples/samples.qdocinc sample-overview - - The \l{writing-topic-commands}{writing topic commands}Ā section has a listing - of the available \\page command arguments. - - \section1 Tutorials, How-To's, FAQ's - - Tutorials, How-To's, and FAQ's are all instructional material, in that they - instruct or prescribe to the reader. Tutorials are content designed to guide - the reader along a progressive learning path for a concept or technology. - How-To's and FAQ's (\e{Frequently Asked Questions}) provide guidance by - presenting material in the form of answers to commonly asked topics. - How-To's and FAQ's are designed for easy reference and are not necessarily - presented in a linear progression. - - To create these types, mark the pages by providing a \c type argument to the - \l{page-command}{\\page} command. The \c type argument is the second - argument, with the file name being the first. - \snippet examples/samples.qdocinc sample-faq - - The \l{writing-topic-commands}{writing topic commands}Ā section has a listing - of the available \\page command arguments. - - \section1 Code Examples - Examples are an effective way to demonstrate practical usage of a given - technology or concept. When it comes to middleware this is usually in the - form of an application using simple code and clear explanations of what the - code is doing. Any module, API, project, pattern etc. should have at least - one good example. - - An example may have an accompanying tutorial. The tutorial instructs and - describes the code, while the code example is the code content that users - may study. Code examples may have accompanying text that are not in the - tutorial. - - QDoc will create a page containing the example code with a description - using the \l{example-command}{\\example} command. - - \snippet examples/samples.qdocinc sample-example - - QDoc will use the directory specified in the input - \l{Input and Output Directories}{exampledirs} variable to find the Qt - Project (\c .pro) file to generate the example files. The generated HTML - will have the filename, \c {declarative-ui-components-tabwidget.html}. QDoc - will also list all of the example code. - - \note The example's project file must be the same as the - directory name. -*/ - - diff --git a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc b/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc deleted file mode 100644 index 8cbf74cd67..0000000000 --- a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-cpp.qdoc +++ /dev/null @@ -1,187 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtwritingstyle-cpp.html -\title C++ Documentation Style -\brief Style guidelines for C++ documentation - -To generate the documentation, QDoc goes through the source code and generates -documentation for C++ types such as classes. QDoc then associates member -functions, properties, and other types to the appropriate class. - -Note that the documentation must be in the implementation files such as \c .cpp. - -\section1 Class Documentation - -Class documentation is generated using the \l{class-command}{\\class} command and -the name of the class as the first argument. - -\snippet examples/cpp.qdoc.sample class - -\l{Context commands} add information about the class, such as its module or -which version the class was added. - -Some common context commands are: -\list -\li \l{brief-command}{\\brief} - the class' brief description \b (mandatory) -\li \l{since-command}{\\since} - the version to which the class was added \b (mandatory) -\li \l{internal-command}{\\internal} - marks the class as internal. Internal -classes do not appear in the public API documentation. -\endlist - - -\section2 The Brief and Detailed Description - -The \e{brief description} is marked with the \l{brief-command}{\\brief} command -and it is for summarizing the purpose or functionality of the class. For C++ -classes, QDoc will take the class and create annotated information for the -class. The annotated information appears in lists and tables which display the -class. - -The C++ brief should start with: -\code -"The <C++ class name> class" -\endcode - -The \e{detailed description} section starts after the brief description. It -provides more information about the class. The detailed description may contain -images, snippet code, or links to other relevant documents. There -must be an empty line which separates the brief and detailed description. - -\section1 Member Functions - -Typically, function documentation immediately precedes the implementation of the -function in the \c .cpp file. For function documentation that is not immediately -above the implementation, the \l{fn-command}{\\fn} is needed. - -\snippet examples/cpp.qdoc.sample function - -The function documentation starts with a verb, indicating the operation the -function performs. This also applies to constructors and destructors. - -Some common verbs for function documentation: -\list -\li "Constructs..." - for constructors -\li "Destroys..." - for destructors -\li "Returns..." - for accessor functions -\endlist - -The function documentation must document: -\list -\li the return type -\li the parameters -\li the actions of the functions -\endlist - -The \l{a-command}{\\a} command marks the parameter in the documentation. -The return type documentation should link to the type documentation or be -marked with the \l{c-command}{\\c} command in the case of boolean values. - -\snippet examples/cpp.qdoc.sample return - -\section1 Properties - -The property documentation resides immediately above the read function's -implementation. The \l{writing-topic-commands}{topic command} for properties is -\l{property-command}{\\property}. - -\snippet examples/cpp.qdoc.sample property - -Property documentation usually starts with "This property...", but these are -alternate expressions: -\list -\li "This property holds..." -\li "This property describes..." -\li "This property represents..." -\li "Returns \c true when... and \c false when..." - for properties that -are read. -\li "Sets the..." - for properties that configure a type. -\endlist - -Property documentation must include: -\list -\li description and behavior of the property -\li accepted values for the property -\li the default value of the property -\endlist -Similar to \l{Member Functions}{functions}, the default type may be linked -or marked with the \c{\c} command. - -An example of a value range style is: -\quotation -The values range from 0.0 (no blur) to maximumRadius (maximum blur). By default, the property is set to 0.0 (no blur). -\endquotation - -\section1 Signals, Notifiers, and Slots -The \l{writing-topic-commands}{topic command} for signals, notifiers, and slots -is \l{fn-command}{\\fn}. Signal documentation state when they are triggered -or emitted. - -\snippet examples/cpp.qdoc.sample signals - -Signal documentation typically begin with "This signal is triggered when...". -Here are alternate styles: -\list -\li "This signal is triggered when..." -\li "Triggered when..." -\li "Emitted when..." -\endlist - -For slots or notifiers, the condition when they are executed or triggered by -a signal should be documented. -\list -\li "Executed when..." -\li "This slot is executed when..." -\endlist - -For properties that have overloaded signals, QDoc groups the overloaded -notifiers together. To refer to a specific version of a notifier or signal, -simply refer to the property and mention that there are different versions of -the notifier. - -\snippet examples/cpp.qdoc.sample overloaded notifier - -\section1 Enums, Namespaces, and Other Types - -Enums, namespaces, and macros have a \l{writing-topic-commands}{topic command} for their documentation: -\list -\li \l{enum-command}{\\enum} -\li \l{typedef-command}{\\typedef} -\li \l{macro-command}{\\macro} -\endlist - -The language style for these types mention that they are an enum or a macro and -continues with the type description. - -For enumerations, the \l{value-command}{\\value} command is for listing the -values. QDoc creates a table of values for the enum. - -\snippet examples/cpp.qdoc.sample enums - -*/ - diff --git a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc b/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc deleted file mode 100644 index 6955a042c2..0000000000 --- a/src/tools/qdoc/doc/qdoc-guide/qtwritingstyle-qml.qdoc +++ /dev/null @@ -1,164 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! -\page qtwritingstyle-qml.html -\title QML Documentation Style -\brief Style guidelines for QML documentation - -QDoc can process QML types defined as C++ classes and QML types defined in -\c .qml files. For C++ classes documented as QML types, the QDoc comments are -in the \c .cpp file while QML types defined in QML are in the \c .qml -file. The C++ classes must also be documented -documented with the QML \l{topic-commands}{topic commands}: - -\list -\li \l{qmlattachedproperty-command}{\\qmlattachedproperty} -\li \l{qmlattachedsignal-command}{\\qmlattachedsignal} -\li \l{qmlbasictype-command}{\\qmlbasictype} -\li \l{qmltype-command}{\\qmltype} -\li \l{qmlmethod-command}{\\qmlmethod} -\li \l{qmlproperty-command}{\\qmlproperty} -\li \l{qmlsignal-command}{\\qmlsignal} -\li \l{qmlmodule-command}{\\qmlmodule} -\li \l{inqmlmodule-command}{\\inqmlmodule} -\li \l{instantiates-command}{\\instantiates} -\endlist - -For QML types defined in \c .qml files, QDoc will parse the QML and determine -the properties, signals, and the type within the QML definition. The QDoc -block then needs to be immediately above the declaration. For QML types -implemented in C++, QDoc will output warnings if the C++ class documentation -does not exist. The class documentation may be marked as -\l{internal-command}{internal} if it is not a public API. - -\section1 QML Types - -The \l{qmltype-command}{\\qmltype} command is for QML type documentation. - -\snippet examples/qml.qdoc.sample qmltype - -The \l{instantiates-command}{\\instantiates} accepts the C++ class which -implements the QML type as the argument. For types implemented in QML, this -is not needed. - -The \e{brief description} provides a summary for the QML type. The brief does -not need to be a complete sentence and may start with a verb. QDoc will append -the brief description onto the QML type in tables and generated lists. - -\code -\qmltype ColorAnimation -\brief Animates changes in color values -\endcode - -Here are some alternate verbs for the brief statement: -\list -\li "Provides..." -\li "Specifies..." -\li "Describes..." -\endlist - -The \e{detailed description} follows the brief and may contain images, snippet, -and link to other documentation. - -\section1 Properties - -The property description focuses on what the property \e does and may use the -following style: - -Property documentation usually starts with "This property..." but for certain -properties, these are the common expressions: -\list -\li "This property holds..." -\li "This property describes..." -\li "This property represents..." -\li "Returns \c true when... and \c false when..." - for properties that -are marked \c{read-only}. -\li "Sets the..." - for properties that configure a type. -\endlist - -\section1 Signals and Handlers Documentation - -QML signals are documented either in the QML file or in the C++ implementation -with the \l{qmlsignal-command}{\\qmlsignal} command. Signal documentation -must include the condition for emitting the signal, mention the corresponding -signal handler, and document whether the signal accepts a parameter. - -\snippet examples/qml.qdoc.sample signals - -These are the possible documentation styles for signals: -\list -\li "This signal is triggered when..." -\li "Triggered when..." -\li "Emitted when..." -\endlist - -\section1 Methods and JavaScript Functions - -Typically, function documentation immediately precedes the implementation of the -function in the \c .cpp file. The \l{topic-commands}{topic command} for -functions is \l{fn-command}{\\fn}. For functions in QML or JavaScript, the -documentation must reside immediately above the function declaration. - -The function documentation starts with a verb, indicating the operation the -function performs. - -\snippet examples/qml.qdoc.sample function - -Some common verbs for function documentation: -\list -\li "Copies..." - for constructors -\li "Destroys..." - for destructors -\li "Returns..." - for accessor functions -\endlist - -The function documentation must document: -\list -\li the return type -\li the parameters -\li the actions of the functions -\endlist - -The \l{a-command}{\\a} command marks the parameter in the documentation. -The return type documentation should link to the type documentation or be -marked with the \l{c-command}{\\c} command in the case of boolean values. - -\section1 Enumerations - -QML enumerations are documented as QML properties with the -\l{qmlproperty-command}{\\qmlproperty} command. The type of the property -is \c enumeration. - -\snippet examples/qml.qdoc.sample enums - -The QDoc comment lists the values of the enumeration. If the enumeration is -implemented in C++, the documentation may link to the corresponding C++ -enumeration. However, the QDoc comment should advise that the enumeration -is a C++ enumeration. - -*/ - diff --git a/src/tools/qdoc/doc/qdoc-manual-DITA.qdoc b/src/tools/qdoc/doc/qdoc-manual-DITA.qdoc deleted file mode 100644 index 72882c8eb1..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual-DITA.qdoc +++ /dev/null @@ -1,164 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 21-0-qdoc-creating-dita-maps.html - \previouspage Miscellaneous - \contentspage QDoc Manual - \nextpage The QDoc Configuration File - - \title Creating DITA Maps - - You can create DITA map files using three new qdoc commands, the \l{ditamap-command} - {ditamap} command, the \l{topicref-command} {topicref} command, and the \l{mapref-command} - {mapref} command. How these DITA maps will be used automatically or manually by the - documentation build process is still under consideration. This section will be updated - as the decisions are made. - - \section1 What is a DITA Map? - - A complete description of DITA can be found at the - \l{http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita} - {OASIS Darwin Information Typing Architecture} site. - - An explanation of the DITA map is found at that site - \l{http://docs.oasis-open.org/dita/v1.2/os/spec/langref/map.html}{here}. - - \target ditamap-command - \section1 \\ditamap - - The \\ditamap command is for creating a DITA map using qdoc commands. - The \\ditamap command is a kind of \\page command that produces a - \e{.ditamap} instead of a \e{.html} or \e{.xml} file. The file that - is created actually contains XML text, but the \e{.ditamap} suffix is - used to identify the file as containing a DITA MAP. - - The argument is the name of the file to be created. In the following - example, the file \e{creator.ditamap} is output: - \code - \ditamap creator.ditamap - \endcode - - \target topicref-command - \section1 \\topicref \\endtopicref - - The \\topicref \\endtopicref commands are for creating a topicref - in the ditamap. The \\endtopicref command is required because - \\topicref commands can be nested. - - \\topicref has two arguments. The first argument becomes the value - of the \e navtitle attribute. Normally, you use the title of the - topic being referenced. This title is often what will appear in a - table of contents constructed from the ditamap. - - The second argument is the name of the page being referenced. The - second argument is actually optional, for example if you are using - a topicref as a container for other topicrefs and maprefs. It is - also optional if you want qdoc to find the page name for you by - looking up the title in its internal data structure. It is recommended - that you provide the second parameter if you know the page name. - - \code - \topicref {QML Module QtQuick 2} {qtquick-2.xml} - \mapref {Creator Manual} {creator-manual.ditamap} \endmapref - \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref - \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref - \endtopicref - \endcode - - \target mapref-command - \section1 \\mapref - - The \\mapref command is for creating a mapref in the ditamap. A - mapref refers to another ditamap, which you want to include in - your ditamap. Like the \\topicref command, the \\mapref command - has two arguments, but for the \\mapref command, both arguments - are required. The arguments are essentially the same as described - for \\topicref, but for \\mapref, the second command must be the - name of another ditamap, i.e. it must have the \e{.ditamap} - suffix. You must provide the file name. qdoc can't look up the - file name for you. - - \code - \mapref {Creator Manual} {creator-manual.ditamap} \endmapref - \endcode - - \section1 An Example Ditamap Page - - The following example uses the three qdoc ditamap commands described above. - - \code - \ditamap creator.ditamap - \title The DITA Map for Creator - - \topicref {QML Module QtQuick 1} - \topicref {QML Mouse Events} \endtopicref - \topicref {Property Binding} \endtopicref - \endtopicref - - \topicref {QML Module QtQuick 2} {qtquick-2.xml} - \mapref {Creator Manual} {creator-manual.ditamap} \endmapref - \topicref {QML Mouse Events} {qtquick2-mouseevents.xml} \endtopicref - \topicref {Property Binding} {qtquick2-propertybinding.xml} \endtopicref - \endtopicref - - \topicref {QML Module QtQuick.Particles 2} {qtquick-particles-2.xml} - \topicref {Age} {qml-qtquick-particles2-age.xml} \endtopicref - \endtopicref - \endcode - - \section1 The Resulting Ditamap File - - This is the \e{.ditamap} file you get when you input the qdoc - ditamap page shown above. Note that you can write ditamap files - directly in XML just as easily as you can write them using the - qdoc commands. The choice is yours. - - \code - <?xml version="1.0" encoding="UTF-8"?> - <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> - <map> - <topicmeta> - <shortdesc>The DITA Map for Creator</shortdesc> - </topicmeta> - <topicref navtitle="QML Module QtQuick 1" href="qtquick-1.xml"> - <topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/> - <topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/> - </topicref> - <topicref navtitle="QML Module QtQuick 2" href="qtquick-2.xml"> - <mapref navtitle="Creator Manual" href="creator-manual.ditamap"/> - <topicref navtitle="QML Mouse Events" href="qtquick2-mouseevents.xml"/> - <topicref navtitle="Property Binding" href="qtquick2-propertybinding.xml"/> - </topicref> - <topicref navtitle="QML Module QtQuick.Particles 2" href="qtquick-particles-2.xml"> - <topicref navtitle="Age" href="qml-qtquick-particles2-age.xml"/> - </topicref> - </map> - \endcode - -*/ - diff --git a/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc b/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc deleted file mode 100644 index d3f188c265..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual-cmdindex.qdoc +++ /dev/null @@ -1,156 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 27-qdoc-commands-alphabetical.html - \previouspage Introduction to QDoc - \contentspage QDoc Manual - \nextpage Topic Commands - - \title Command Index - - This is a complete, alphabetized list of the QDoc commands. - - \list - - \li \l {a-command} {\\a} - \li \l {abstract-command} {\\abstract} - \li \l {annotatedlist-command} {\\annotatedlist} - \li \l {b-command} {\\b} - \li \l {b-command} {\\bold} \span {class="newStuff"} {(deprecated, use \\b)} - \li \l {brief-command} {\\brief} - \li \l {c-command} {\\c} - \li \l {caption-command} {\\caption} - \li \l {chapter-command} {\\chapter} - \li \l {class-command} {\\class} - \li \l {code-command} {\\code} - \li \l {codeline-command} {\\codeline}, - \li \l {compat-command} {\\compat} - \li \l {contentspage-command} {\\contentspage} - \li \l {default-command} {\\default} - \li \l {div-command} {\\div} - \li \l {dots-command} {\\dots} - \li \l {e-command} {\\e} - \li \l {else-command} {\\else} - \li \l {endif-command} {\\endif} - \li \l {enum-command} {\\enum} - \li \l {example-command} {\\example} - \li \l {externalpage-command} {\\externalpage} - \li \l {fn-command} {\\fn} - \li \l {footnote-command} {\\footnote} - \li \l {generatelist-command} {\\generatelist} - \li \l {group-command} {\\group} - \li \l {header-command} {\\header} - \li \l {headerfile-command} {\\headerfile} - \li \l {e-command} {\\i} \span {class="newStuff"} {(deprecated, use \\e)} - \li \l {if-command} {\\if} - \li \l {image-command} {\\image} - \li \l {include-command} {\\include} - \li \l {indexpage-command} {\\indexpage} - \li \l {ingroup-command} {\\ingroup} - \li \l {inherits-command}{\\inherits} - \li \l {inlineimage-command} {\\inlineimage} - \li \l {inmodule-command} {\\inmodule} - \li \l {inqmlmodule-command} {\\inqmlmodule} - \li \l {instantiates-command} {\\instantiates} - \li \l {internal-command} {\\internal} - \li \l {keyword-command} {\\keyword} - \li \l {l-command} {\\l} - \li \l {legalese-command} {\\legalese} - \li \l {li-command} {\\li} - \li \l {list-command} {\\list} - \li \l {macro-command} {\\macro} - \li \l {meta-command} {\\meta} - \li \l {module-command} {\\module} - \li \l {namespace-command} {\\namespace} - \li \l {nextpage-command} {\\nextpage} - \li \l {newcode-command} {\\newcode} - \li \l {noautolist-command} {\\noautolist} - \li \l {nonreentrant-command} {\\nonreentrant} - \li \l {note-command} {\\note} - \li \l {li-command} {\\o} \span {class="newStuff"} {(deprecated, use \\li)} - - \li \l {obsolete-command} {\\obsolete} - \li \l {oldcode-command} {\\oldcode} - \li \l {omit-command} {\\omit} - \li \l {omitvalue-command} {\\omitvalue} - \li \l {overload-command} {\\overload} - \li \l {page-command} {\\page} - \li \l {part-command} {\\part} - \li \l {preliminary-command} {\\preliminary} - \li \l {previouspage-command} {\\previouspage} - \li \l {printline-command} {\\printline} - \li \l {printto-command} {\\printto} - \li \l {printuntil-command} {\\printuntil} - \li \l {property-command} {\\property} - \li \l {qmlabstract-command} {\\qmlabstract} - \li \l {qmlattachedproperty-command} {\\qmlattachedproperty} - \li \l {qmlattachedsignal-command} {\\qmlattachedsignal} - \li \l {qmlbasictype-command} {\\qmlbasictype} - \li \l {qmlclass-command} {\\qmlclass} \span {class="newStuff"} {(deprecated, use \\qmltype)} - \li \l {qmltype-command} {\\qmltype} - \li \l {qmlmethod-command} {\\qmlmethod} - \li \l {qmlproperty-command} {\\qmlproperty} - \li \l {qmlsignal-command} {\\qmlsignal} - \li \l {qmlmodule-command} {\\qmlmodule} - \li \l {quotation-command} {\\quotation} - \li \l {quotefile-command} {\\quotefile} - \li \l {quotefromfile-command} {\\quotefromfile} - \li \l {raw-command} {\\raw} - \li \l {reentrant-command} {\\reentrant} - \li \l {reimp-command} {\\reimp} - \li \l {relates-command} {\\relates} - \li \l {row-command} {\\row} - \li \l {sa-command} {\\sa} - \li \l {sectionOne-command} {\\section1} - \li \l {sectionTwo-command} {\\section2} - \li \l {sectionThree-command} {\\section3} - \li \l {sectionFour-command} {\\section4} - \li \l {since-command} {\\since} - \li \l {skipline-command} {\\skipline} - \li \l {skipto-command} {\\skipto} - \li \l {skipuntil-command} {\\skipuntil} - \li \l {snippet-command} {\\snippet}, - \li \l {span-command} {\\span} - \li \l {startpage-command} {\\startpage} - \li \l {sub-command} {\\sub} - \li \l {subtitle-command} {\\subtitle} - \li \l {sup-command} {\\sup} - \li \l {table-command} {\\table} - \li \l {tableofcontents-command} {\\tableofcontents} - \li \l {target-command} {\\target} - \li \l {threadsafe-command} {\\threadsafe} - \li \l {title-command} {\\title} - \li \l {tt-command} {\\tt} - \li \l {typedef-command} {\\typedef} - \li \l {uicontrol-command} {\\uicontrol} - \li \l {underline-command} {\\underline} - \li \l {variable-command} {\\variable} - \li \l {value-command} {\\value} - \li \l {warning-command} {\\warning} - \endlist -*/ diff --git a/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc deleted file mode 100644 index d707c77cfb..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual-contextcmds.qdoc +++ /dev/null @@ -1,1058 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 14-qdoc-commands-contextcommands.html - \previouspage Topic Commands - \contentspage QDoc Manual - \nextpage Document Navigation - - \title Context Commands - - The context commands provide information about the element being - documented that QDoc can't deduce on its own. For example: - \list - \li Is this class thread-safe? - \li Is this function reentrant? - \li Of which module is this class a member ? - \endlist - - Context commands can appear anywhere in a QDoc comment, - but they are normally placed near the top of the comment, just - below the \l {Topic Commands} {topic} command. - - \list - \li \l {abstract-command} {\\abstract} - \li \l {compat-command}{\\compat}, - \li \l {contentspage-command}{\\contentspage}, - \li \l {indexpage-command}{\\indexpage}, - \li \l {ingroup-command}{\\ingroup}, - \li \l {inherits-command}{\\inherits}, - \li \l {inmodule-command}{\\inmodule}, - \li \l {internal-command}{\\internal}, - \li \l {nextpage-command}{\\nextpage}, - \li \l {nonreentrant-command}{\\nonreentrant}, - \li \l {obsolete-command}{\\obsolete}, - \li \l {overload-command}{\\overload}, - \li \l {preliminary-command}{\\preliminary}, - \li \l {previouspage-command}{\\previouspage}, - \li \l {qmlabstract-command} {\\qmlabstract} - \li \l {reentrant-command}{\\reentrant}, - \li \l {reimp-command}{\\reimp}, - \li \l {relates-command}{\\relates}, - \li \l {since-command}{\\since}, - \li \l {startpage-command}{\\startpage}, - \li \l {subtitle-command}{\\subtitle} - \li \l {threadsafe-command}{\\threadsafe}, - \li \l {title-command}{\\title} - \endlist - -*/ - -/*! - \page 15-qdoc-commands-navigation.html - \previouspage Context Commands - \contentspage QDoc Manual - \nextpage Status - - \title Document Navigation - - The navigation commands are for linking the pages of a document in - a meaningful sequence. Below is a sequence of QDoc comments that - shows a typical use of the navigation commands. - - \section1 Example - \quotefile files/basicqt.qdoc.sample - - QDoc renders the "Getting Started" page in \c{creatingdialogs.html}: - - \quotation - \raw HTML - <table border="0" cellpadding="0" cellspacing="5" width="100%"> - - <tr> - <p> - [Previous: <a href="15-qdoc-commands-navigation.html#deadlink"> - Basic Qt</a>] - [<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>] - [Next: <a href="15-qdoc-commands-navigation.html#deadlink"> - Creating Dialogs</a>] - </p> - - <h1 align="center">Getting Started<br /></h1> - - <p> - This chapter shows how to combine basic C++ with the - functionality provided by Qt to create a few small graphical - interface (GUI) applications. - </p> - - <p> - [Previous: <a href="15-qdoc-commands-navigation.html#deadlink"> - Basic Qt</a>] - [<a href="15-qdoc-commands-navigation.html#deadlink">Contents</a>] - [Next: <a href="15-qdoc-commands-navigation.html#deadlink"> - Creating Dialogs</a>] - </p> - - </table> - \endraw - \endquotation - - The \l {indexpage-command} {\\indexpage} and \l - {startpage-command} {\\startpage} commands create links to the - page's index page and start page. These links can be used by - browsers and search engines. - - The index page is typically an alphabetical list of the document's - titles and topics, while the start page is the page considered by - the author to be the starting point of a multipage document. - - The links are included in the generated HTML source code, but have - no visual effect on the documentation: - - \code - <head> - ... - <link rel="index" href="index.html" /> - <link rel="start" href="basicqt.html" /> - ... - </head> - \endcode - - \section1 Commands - - \target previouspage-command - \section2 \\previouspage - - The \\previouspage command links the current page to the previous - page in a sequence.a The command has two arguments, each enclosed - by curly braces: the first is the link target (the title of - the previous page), the second is the link text. If the page's - title is equivalent to the link text, the second argument can be - omitted. - - The command must stand alone on its own line. - - \target nextpage-command - \section2 \\nextpage - - The \\nextpage command links the current page to the next page in - a sequence. The command follows the same syntax and argument - convention as the \l {previouspage-command} {\\previouspage} - command. - - \target startpage-command - \section2 \\startpage - - The \\startpage command specifies the first page of a sequence of - pages. The command must stand alone on its own line, and its - unique argument is the title of the first document. - - QDoc will generate a link to the start page and include it in the - generated HTML file, but this has no visual effect on the - documentation. The generated link type tells browsers and search - engines which document is considered by the author to be the - starting point of the collection. - - \target contentspage-command - \section2 \\contentspage - - The \\contentspage command links the current page to a table of - contents page. The command follows the same syntax and argument - convention as the \l {previouspage-command} {\\previouspage} - command. - - \target indexpage-command - \section2 \\indexpage - - The \\indexpage command specifies an index page for the current - document. The command must stand alone on its own line, and its - unique argument is the title of the index document. - - QDoc will generate a link to the index page and include it in the - generated HTML file, but this has no visual effect on the - documentation. The generated link type tells browsers and search - engines which document is considered by the author to be the - index page of the collection. -*/ - -/*! - \page 16-qdoc-commands-status.html - \previouspage Document Navigation - \contentspage QDoc Manual - \nextpage Thread Support - - \title Status - - These commands are for indicating that a documented element has - some special status. The element could be marked as about to be - made obsolete, or that it is provided for compatibility with an - earlier version, or is simply not to be included in the public - interface. The \l {since-command}{\\since} command is for - specifying the version number in which a function or class first - appeared. The \l {qmlabstract-command} {\\qmlabstract} command is - for marking a QML type as an abstract base class. - - \target abstract-command - \target qmlabstract-command - \section1 \\abstract and \\qmlabstract - - \\abstract is a synonym for the \\qmlabstract command. Add this - command to the \l {qmltype-command} {\\qmltype} comment for a QML - type when that type is meant to be used \e {only} as an abstract - base type. When a QML type is abstract, it means that the QML type - that can't be instantiated. Instead, the properties in its public - API are included in the public properties list on the reference - page for each QML type that inherits the abstract QML type. The - properties are documented as if they are properties of the - inheriting QML type. - - Normally, when a QML type is marked with \e{\\qmlabstract}, it is - also marked with \e{\\internal} so that its reference page is not - generated. It the abstract QML type is not marked internal, it - will have a reference page in the documentation. - - \target compat-command - \section1 \\compat - - The \\compat command is for indicating that a class or function is - part of the support library provided to keep old source code - working. - - The command must stand on its own line. - - Usually an equivalent function or class is provided as an - alternative. - - If the command is used in the documentation of a class, the - command expands to a warning that the referenced class is part of - the support library. The warning is located at the top of the - documentation page. - - \code - \beginqdoc - \class MyQt3SupportClass - \compat - \endqdoc - \endcode - - QDoc renders this at the top of the MyQt3SupportClass class - reference page. - - \quotation - \b {This class is part of the Qt 3 support - library.} It is provided to keep old source code - working. We strongly advise against using it in new - code. See the \l - {http://doc.qt.io/qt-4.8/porting4.html} {Porting - Guide} for more information. - \endquotation - - If the command is used when documenting a function, QDoc will - create and link to a separate page documenting Qt 3 support - members when generating the reference documentation for the - associated class. - - \code - \beginqdoc - \fn MyClass::MyQt3SupportMemberFunction - \compat - - Use MyNewFunction() instead. - \endqdoc - \endcode - - QDoc renders this in \c{myclass-qt3.html} as: - - \quotation - \raw HTML - <h1>Qt 3 Support Members for MyClass</h1> - \endraw - - \b {The following class members are part of the Qt 3 - support layer.} They are provided to help you port old code to - Qt 4. We advise against using them in new code. - - ... - - \list - \li void MyQt3SupportMemberFunction() - \li ... - \endlist - - \raw HTML - <hr /> - <h2>Member Function Documentation</h2> - <h3>void MyQt3SupportMemberFunction ()</h3> - <p>Use MyNewFunction() instead.</p> - \endraw - ... - \endquotation - - \target default-command - \section1 \\default - - The \\default command is for marking a QML property as the - \l {default-properties} - {default property}. The word \span {class="newStuff"} {default} is shown in red in - the documentation of the property. - - \code - / *! - \qmlproperty list<Change> State::changes - This property holds the changes to apply for this state. - \default - - By default these changes are applied against the default state. If the state - extends another state, then the changes are applied against the state being - extended. - * / - \endcode - - See how QDoc renders this property on the reference page for the - \l {State::changes}{State} type. - - \target obsolete-command - \section1 \\obsolete - - The \\obsolete command is for indicating that a function is being - deprecated, and it should no longer be used in new code. There is - no guarantee for how long it will remain in the library. - - The command must stand on its own line. - - When generating the reference documentation for a class, QDoc will - create and link to a separate page documenting its obsolete - functions. Usually an equivalent function is provided as an - alternative. - - \code - / *! - \fn MyClass::MyObsoleteFunction - \obsolete - - Use MyNewFunction() instead. - * / - \endcode - - QDoc renders this in \c{myclass-obsolete.html} as: - - \quotation - \raw HTML - <h1>Obsolete Members for MyClass</h1> - \endraw - - \b {The following class members are obsolete.} They are - provided to keep old source code working. We strongly advise - against using them in new code. - - ... - - \list - \li void MyObsoleteFunction() \c (obsolete) - \li ... - \endlist - - \raw HTML - <hr /> - <h2>Member Function Documentation</h2> - <h3>void MyObsoleteFunction ()</h3> - <p>Use MyNewFunction() instead.</p> - \endraw - ... - \endquotation - - \target internal-command - \section1 \\internal - - The \\internal command indicates that the referenced - function is not part of the public interface. - - The command must stand on its own line. - - QDoc ignores the documentation as well as the documented item, - when generating the associated class reference documentation. - - \code - / *! - \internal - - Tries to find the decimal separator. If it can't find - it and the thousand delimiter is != '.' it will try to - find a '.'; - * / - int QDoubleSpinBoxPrivate::findDelimiter - (const QString &str, int index) const - { - int dotindex = str.indexOf(delimiter, index); - if (dotindex == -1 && thousand != dot && delimiter != dot) - dotindex = str.indexOf(dot, index); - return dotindex; - } - \endcode - - This function will not be included in the documentation. - - \target preliminary-command - \section1 \\preliminary - - The \\preliminary command is for indicating that a referenced - function is still under development. - - The command must stand on its own line. - - The \\preliminary command expands to a notification in the - function documentation, and marks the function as preliminary when - it appears in lists. - - \code - / *! - \preliminary - - Returns information about the joining type attributes of the - character (needed for certain languages such as Arabic or - Syriac). - - * / - QChar::JoiningType QChar::joiningType() const - { - return QChar::joiningType(ucs); - } - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h3> - <a href="http://doc.qt.io/qt-5/qchar.html#JoiningType-enum">JoiningType</a> - QChar::joiningType() const</h3> - \endraw - - \b {This function is under development and - subject to change.} - - Returns information about the joining type attributes of the - character (needed for certain languages such as Arabic or - Syriac). - \endquotation - - And the function's entry in QChar's list of public functions will be - rendered as: - - \quotation - \list - \li ... - \li JoiningType \l {QChar::joiningType()} {joiningType}() const \c (preliminary) - \li ... - \endlist - \endquotation - - \target since-command - \section1 \\since - - The \\since command tells in which minor release - the associated functionality was added. - - \code - / *! - \since 4.1 - - Returns an icon for \a standardIcon. - - ... - - \sa standardPixmap() - * / - QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const - { - } - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h3>QIcon QStyle::standardIcon(StandardPixmap standardIcon, const QStyleOption *option, const QWidget *widget) const</h3> - \endraw - - This function was introduced in Qt version 4.1 - - Returns an icon for \a standardIcon. - - ... - - See also \l {QStyle::standardPixmap()} {standardPixmap()}. - \endquotation - - QDoc generates the "Qt" reference from the \l - {25-qdoc-configuration-derivedprojects.html#project} {\c project} - configuration variable. For that reason this reference will change - according to the current documentation project. - - See also \l {project} - {\c project}. -*/ - - -/*! - \page 17-qdoc-commands-thread.html - \previouspage Status - \contentspage QDoc Manual - \nextpage Relating Things - - \title Thread Support - - The thread support commands are for specifying the level of - support for multithreaded programming in a class or function. - There are three levels of support: \c threadsafe, \c reentrant and - \c nonreentrant. - - The default is \c nonreentrant which means that the associated - class or function cannot be called by multiple threads. \c - Reentrant and \c threadsafe are levels primarily used for classes. - - \c Reentrant means that all the functions in the referenced class - can be called simultaneously by multiple threads, provided that - each invocation of the functions reference unique data. While \c - threadsafe means that all the functions in the referenced class - can be called simultaneously by multiple threads even when each - invocation references shared data. - - When a class is marked \l {reentrant-command} {\\reentrant} or \l - {threadsafe-command} {\\threadsafe}, functions in that class can - be marked \c nonreentrant using the \l {nonreentrant-command} - {\\nonreentrant} command. - - \section1 Example - - \target reentrant-example - \code - \beginqdoc - \class QLocale - \brief The QLocale class converts between numbers and their - string representations in various languages. - - \reentrant - \ingroup i18n - \ingroup text - - QLocale is initialized with a language/country pair in its - constructor and offers number-to-string and string-to-number - conversion functions similar to those in QString. - - ... - - \nonreentrant - - Sets the global default locale to \a locale. These values are - used when a QLocale object is constructed with no - arguments. If this function is not called, the system's locale - is used. - - \warning In a multithreaded application, the default locale - should be set at application startup, before any non-GUI - threads are created. - - \sa system(), c() - \endqdoc - void QLocale::setDefault(const QLocale &locale) - { - default_d = locale.d; - } - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h1><center>QLocale Class Reference</center></h1> - \endraw - - The QLocale class converts between numbers and their string - representations in various languages. More... - - \code - #include <QLocale> - \endcode - - \b {Note:} All the functions in this class are \l - {17-qdoc-commands-thread.html#reentrant} {reentrant}, except \l - {QLocale::setDefault()} {setDefault()}. - - ... - - \raw HTML - <hr /> - <h2>Member Type Documentation</h2> - \endraw - - ... - - \raw HTML - <h3>void QLocale::setDefault ( const QLocale & locale ) </h3> - \endraw - - Sets the global default locale to locale. These values are - used when a QLocale object is constructed with no - arguments. If this function is not called, the system's locale - is used. - - \warning In a multithreaded application, the default locale - should be set at application startup, before any non-GUI - threads are created. - - \warning This function is not reentrant. - - See also \l {QLocale::system()} {system()} and \l - {QLocale::c()} {c()}. - - ... - \endquotation - - As shown above, QDoc generates a notification when a class is - declared reentrant, and lists the exceptions (the declared - nonreentrant functions). A link to the general documentation on \l - {17-qdoc-commands-thread.html#reentrant} {reentrancy and thread-safety} is - included. In addition a warning, "\b Warning: This function is - not reentrant.", is generated in the nonreentrant functions' - documentation. - - QDoc will generate the same notification and warnings when a class - is declared threadsafe. - - For more information see the general documentation on \l - {17-qdoc-commands-thread.html#reentrant} {reentrancy and thread-safety}. - - \section1 Commands - - \target threadsafe-command - \section2 \\threadsafe - - The \\threadsafe command includes a line in the documentation to - indicate that the associated class or function is \e threadsafe - and can be called simultaneously by multiple threads, even when - separate invocations reference shared data. - - The command must stand on its own line. - - The documentation generated from this command will be similar to - the what is generated for the \l {reentrant-command} {\\reentrant} - command. See the example above in the \l {reentrant-example} - {introduction}. - - See also \l{reentrant-command} {\\reentrant} and - \l{nonreentrant-command} {\\nonreentrant}. - - \target reentrant-command - \section2 \\reentrant - - The \\reentrant command indicates that the associated class or - function can be called simultaneously by multiple threads, - provided that each invocation references its own data. See the \l - {reentrant-example} {example} above. - - The command must stand on its own line. - - See also \l{nonreentrant-command} {\\nonreentrant} and - \l{threadsafe-command} {\\threadsafe}. - - \target nonreentrant-command - \section2 \\nonreentrant - - The \\nonreentrant command indicates that the associated class or - function cannot be called by multiple threads. Nonreentrant is the - default case. - - The command must stand on its own line. - - When a class is marked \l {reentrant-command} {\\reentrant} or \l - {threadsafe-command} {\\threadsafe}, functions in that class can - be marked \c nonreentrant using this command in the \l{fn-command} - {\\fn} comment of the functions to be excluded. - - See also \l{reentrant-command} {\\reentrant} and - \l{threadsafe-command} {\\threadsafe}. -*/ - -/*! - \page 18-qdoc-commands-relating.html - \previouspage Thread Support - \contentspage QDoc Manual - \nextpage Grouping Things - - \title Relating Things - - The relating commands are for specifying how one documented - element relates to another documented element. Some examples: - \list - \li This function is an overload of another function. - \li This function is a reimplementation of another function. - \li This typedef is \e related to some class or header file. - \endlist - - There is also a command for documenting that a QML type inherits - some other QML type. - - \section1 Commands - - \target inherits-command - \section2 \\inherits - - The \\inherits command is for documenting that one QML type - inherits some other QML type. It must be included in the - inheriting element's \l{qmltype-command}{\\qmltype} comment. - The argument is the name of the inherited QML type. - - \code - / *! - \qmltype PauseAnimation - \instantiates QDeclarativePauseAnimation - \ingroup qml-animation-transition - \since 4.7 - \inherits Animation - \brief The PauseAnimation element provides a pause for an animation. - - When used in a SequentialAnimation, PauseAnimation is a step - when nothing happens, for a specified duration. - - A 500ms animation sequence, with a 100ms pause between two animations: - - SequentialAnimation { - NumberAnimation { ... duration: 200 } - PauseAnimation { duration: 100 } - NumberAnimation { ... duration: 200 } - } - - \sa {QML Animation and Transitions}, {declarative/animation/basics}{Animation basics example} - * / - \endcode - - QDoc includes this line on the reference page for the - \l{http://qt-project.org/doc/qt-4.7/qml-pauseanimation.html} {PauseAnimation} - element: - - \quotation - Inherits \l{http://qt-project.org/doc/qt-4.7/qml-animation.html} {Animation} - \endquotation - - \target overload-command - \section2 \\overload - - The \\overload command is for indicating that a function is a - secondary overload of its name. - - The command must stand on its own line. - - For a function name that is overloaded (except constructors), QDoc - expects one primary version of the function, and all the others - marked with the \b {\\overload command}. The primary version - should be fully documented. Each overload can have whatever extra - documentation you want to add for just that overloaded version. - - From Qt 4.5, you can include the function name plus '()' as a - parameter to the \b{\\overload} command, which will include a - standard \e{This function overloads...} line of text with a link - to the documentation for the primary version of the function. - - \code - / *! - \overload addAction() - - This convenience function creates a new action with an - \a icon and some \a text. The function adds the newly - created action to the menu's list of actions, and - returns it. - - \sa QWidget::addAction() - * / - QAction *QMenu::addAction(const QIcon &icon, const QString &text) - { - QAction *ret = new QAction(icon, text, this); - addAction(ret); - return ret; - } - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h3><a href="http://doc.qt.io/qt-5/qaction.html">QAction</a> - * QMenu::addAction ( const QIcon & <i>icon</i>, - const QString & <i>text</i> ) - </h3> - \endraw - - This function overloads \l {QMenu::addAction()} {addAction()} - - This convenience function creates a new action with an - \e icon and some \e text. The function adds the newly - created action to the menu's list of actions, and - returns it. - - See also - \l {QWidget::addAction()} {QWidget::addAction}(). - \endquotation - - If you don't include the function name with the \b{\\overload} - command, then instead of the "This function overloads..." line - with the link to the documentation for the primary version, you - get the old standard line: - - \quotation - This is an overloaded member function, provided for - convenience. - \endquotation. - - \target reimp-command - \section2 \\reimp - - The \\reimp command is for indicating that a function is a - reimplementation of a virtual function. - - The command must stand on its own line. - - QDoc will omit the reimplemented function from the class - reference. - - \code - / *! - \reimp - * / - void QToolButton::nextCheckState() - { - Q_D(QToolButton); - if (!d->defaultAction) - QAbstractButton::nextCheckState(); - else - d->defaultAction->trigger(); - } - \endcode - - This function will not be included in the documentation. Instead, - a link to the base function QAbstractButton::nextCheckState() will - appear in the documentation. - - \target relates-command - \section2 \\relates - - The \\relates command is for including the documentation of a - global element to some class or header file. The argument is a - class name or header file. - - \code - / *! - \relates QChar - - Reads a char from the stream \a in into char \a chr. - - \sa {Format of the QDataStream operators} - * / - QDataStream &operator>>(QDataStream &in, QChar &chr) - { - quint16 u; - in >> u; - chr.unicode() = ushort(u); - return in; - } - \endcode - - The documentation for this function will be included on the reference page - for class QChar. -*/ - -/*! - \page 19-qdoc-commands-grouping.html - \previouspage Relating Things - \contentspage QDoc Manual - \nextpage Naming Things - - \title Grouping Things - - The grouping commands relate classes to defined groups and - modules. The groups are used when generating lists of related - classes in the documentation, while the modules are elements of - Qt's structure. - - \section1 Commands - - \target ingroup-command - \section2 \\ingroup - - The \\ingroup command indicates that the given - overview or documented class belongs to a certain group of - related docmentation. - - A class or overview may belong to many groups. - - The \\ingroup command's argument is a group name, but note - that the command considers the rest of the line as part of - its argument. Make sure that the group name is followed by - a linebreak. - - \code - / *! - \class QDir - \brief The QDir class provides access to directory - structures and their contents. - - \ingroup io - ... - * / - \endcode - - This will include the QDir class in the \c io group, which means, - for example, that QDir will appear on the list created by calling - the \l {group-command} {\\group} command with the \c io argument. - - To list overviews that are related to a certain group, you must - generate the list explicitly using the \l {generatelist-command} - {\\generatelist} command with the \c related argument. - - See also \l {group-command} {\\group}. - - \target inmodule-command - \section2 \\inmodule - - The \\inmodule command relates a class to the module specified by - the command's argument. - - For the basic classes in Qt, a class's module is determined by its - location, namely its directory. However, for extensions like - ActiveQt and Qt Designer, a class must be related to a module - explicitly. - - The command's argument is a module name, but note that the command - considers the rest of the line as part of its argument. Make sure - that the module name is followed by a linebreak. - - \code - /*! - \class QDesignerTaskMenuExtension - \inmodule QtDesigner - * / - \endcode - - This ensures that the QDesignerTaskMenuExtension class is included - in the Qt Designer module, which means, for example, that the - class will appear on the list created by calling the \l - {generatelist-command} {\\generatelist} command with the \c - {{classesbymodule QtDesigner}} argument. - - See also \l {module-command} {\\module} and \l - {generatelist-command} {\\generatelist}. -*/ - -/*! - \page 20-qdoc-commands-namingthings.html - \previouspage Grouping Things - \contentspage QDoc Manual - \nextpage Markup Commands - - \title Naming Things - - In general, a title command considers everything that follows it - until the first line break as its argument. If the title is so - long it must span multiple lines, end each line (except the last - one) with a backslash. - - \section1 Commands - - \target title-command - \section2 \\title - - The \\title command sets the title for a documentation page, or - allows you to override it. - - \code - / *! - \page signalandslots.html - - \title Signals & Slots - - Signals and slots are used for communication between - objects. The signals and slots mechanism is a central - feature of Qt, and probably the part that differs most - from the features provided by other frameworks. - - ... - * / - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h1><center>Signal and Slots</center></h1> - \endraw - - Signals and slots are used for communication between - objects. The signals and slots mechanism is a central - feature of Qt and probably the part that differs most - from the features provided by other frameworks. - ... - \endquotation - See also \l {subtitle-command} {\\subtitle}. - - \target subtitle-command - \section2 \\subtitle - - The \\subtitle command sets a subtitle for a documentation page. - - \code - \beginqdoc - \page qtopiacore-overview.html - - \title Qtopia Core - \subtitle Qt for Embedded Linux - - Qt/Embedded, the embedded Linux port of Qt, is a - complete and self-contained C++ GUI and platform - development tool for Linux-based embedded development. - ... - \endqdoc - \endcode - - QDoc renders this as: - - \quotation - \raw HTML - <h1><center>Qtopia Core</center></h1> - <h2><center>Qt for Embedded Linux</center></h2> - \endraw - - Qt/Embedded, the embedded Linux port of Qt, is a - complete and self-contained C++ GUI and platform - development tool for Linux-based embedded development. - ... - \endquotation - - See also \l {title-command} {\\title}. - -*/ diff --git a/src/tools/qdoc/doc/qdoc-manual-intro.qdoc b/src/tools/qdoc/doc/qdoc-manual-intro.qdoc deleted file mode 100644 index 84f9416843..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual-intro.qdoc +++ /dev/null @@ -1,325 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 01-qdoc-manual.html - \contentspage QDoc Manual - \previouspage QDoc Manual - \nextpage Command Index - - \title Introduction to QDoc - - QDoc is a tool used by Qt Developers to generate documentation for - software projects. It works by extracting \e {QDoc comments} from - project source files and then formatting these comments as HTML - pages or DITA XML documents. QDoc finds QDoc comments in \c - {.cpp} files and in \c {.qdoc} files. QDoc does not look for QDoc - comments in \c {.h} files. A QDoc comment always begins with an - exclamation mark (\b{!})). For example: - - \code - / *! - \class QObject - \brief The QObject class is the base class of all Qt objects. - - \ingroup objectmodel - - \reentrant - - QObject is the heart of the Qt \l{Object Model}. The - central feature in this model is a very powerful mechanism - for seamless object communication called \l{signals and - slots}. You can connect a signal to a slot with connect() - and destroy the connection with disconnect(). To avoid - never ending notification loops you can temporarily block - signals with blockSignals(). The protected functions - connectNotify() and disconnectNotify() make it possible to - track connections. - - QObjects organize themselves in \l {Object Trees & - Ownership} {object trees}. When you create a QObject with - another object as parent, the object will automatically - add itself to the parent's \c children() list. The parent - takes ownership of the object. It will automatically - delete its children in its destructor. You can look for an - object by name and optionally type using findChild() or - findChildren(). - - Every object has an objectName() and its class name can be - found via the corresponding metaObject() (see - QMetaObject::className()). You can determine whether the - object's class inherits another class in the QObject - inheritance hierarchy by using the \c inherits() function. - - .... - * / - \endcode - - From the QDoc comment above, QDoc generates the HTML \l {QObject} - {QObject class reference} page. - - This manual explains how to use the QDoc commands in QDoc comments - to embed good documentation in your source files. It also explains - how to make a \l {The QDoc Configuration File} {QDoc configuration - file}, which you will pass to QDoc on the command line. - - \section1 Running QDoc - - The name of the QDoc program is \c {qdoc}. To run qdoc from the - command line, give it the name of a configuration file: - - \quotation - \c {$ ../../bin/qdoc ./config.qdocconf} - \endquotation - - QDoc recognizes the \c {.qdocconf} suffix as a \l{The QDoc - Configuration File} {QDoc configuration file}. The configuration - file is where you tell QDoc where to find the project source - files, header files, and \c {.qdoc} files. It is also where you - tell QDoc what kind of output to generate (HTML, DITA XML,...), - and where to put the generated documentation. The configuration - file also contains other information for QDoc. - - See \l{The QDoc Configuration File} for instructions on how to - set up a QDoc configuration file. - - \section2 Running QDoc in Single Execution Mode - - Beginning with Qt 5.5, a new way to run QDoc is available that - reduces the time it takes to generate the Qt5 documentation by as - much as 90%. The new way to run QDoc is \e{single execution} mode. - Single execution mode is not currently available in the Qt5 build - system, which still uses the \e {standard} mode. Single execution - mode is only available when you run QDoc yourself, which you will - want to do often as you document your module and integrate your - documentation with the other Qt modules. - - To run QDoc in single execution mode, add \c {-single-exec} to the - command line and pass QDoc a master \c qdocconf file that is - simply a list of file paths for qdocconf files of all the Qt5 - modules. For example: - - \code - /Users/me/qt5/qtbase/bin/qdoc -outputdir /Users/me/qt5/qtbase/doc -installdir /Users/me/qt5/qtbase/doc /Users/me/qt5/master.qdocconf -single-exec - \endcode - - The qdocconf file, \c {master.qdocconf}, just lists the qdocconf files for all the Qt5 modules to be processed: - - \badcode - /Users/me/qt5/qtbase/src/corelib/doc/qtcore.qdocconf - /Users/me/qt5/qtbase/src/network/doc/qtnetwork.qdocconf - /Users/me/qt5/qtbase/src/sql/doc/qtsql.qdocconf - /Users/me/qt5/qtbase/src/xml/doc/qtxml.qdocconf - /Users/me/qt5/qtbase/src/testlib/doc/qttestlib.qdocconf - /Users/me/qt5/qtbase/src/concurrent/doc/qtconcurrent.qdocconf - /Users/me/qt5/qtbase/src/gui/doc/qtgui.qdocconf - /Users/me/qt5/qtbase/src/platformheaders/doc/qtplatformheaders.qdocconf - /Users/me/qt5/qtbase/src/widgets/doc/qtwidgets.qdocconf - /Users/me/qt5/qtbase/src/opengl/doc/qtopengl.qdocconf - /Users/me/qt5/qtbase/src/printsupport/doc/qtprintsupport.qdocconf - /Users/me/qt5/qtbase/src/tools/qdoc/doc/config/qdoc.qdocconf - /Users/me/qt5/qtbase/qmake/doc/qmake.qdocconf - /Users/me/qt5/qtsvg/src/svg/doc/qtsvg.qdocconf - /Users/me/qt5/qtxmlpatterns/src/xmlpatterns/doc/qtxmlpatterns.qdocconf - /Users/me/qt5/qtdeclarative/src/qml/doc/qtqml.qdocconf - /Users/me/qt5/qtdeclarative/src/quick/doc/qtquick.qdocconf - /Users/me/qt5/qtquickcontrols/src/controls/doc/qtquickcontrols.qdocconf - /Users/me/qt5/qtquickcontrols/src/layouts/doc/qtquicklayouts.qdocconf - /Users/me/qt5/qtquickcontrols/src/dialogs/doc/qtquickdialogs.qdocconf - /Users/me/qt5/qtmultimedia/src/multimedia/doc/qtmultimedia.qdocconf - /Users/me/qt5/qtmultimedia/src/multimediawidgets/doc/qtmultimediawidgets.qdocconf - /Users/me/qt5/qtactiveqt/src/activeqt/doc/activeqt.qdocconf - /Users/me/qt5/qtsensors/src/sensors/doc/qtsensors.qdocconf - /Users/me/qt5/qtwebkit/Source/qtwebkit.qdocconf - /Users/me/qt5/qttools/src/assistant/help/doc/qthelp.qdocconf - /Users/me/qt5/qttools/src/assistant/assistant/doc/qtassistant.qdocconf - /Users/me/qt5/qttools/src/designer/src/uitools/doc/qtuitools.qdocconf - /Users/me/qt5/qttools/src/designer/src/designer/doc/qtdesigner.qdocconf - /Users/me/qt5/qttools/src/linguist/linguist/doc/qtlinguist.qdocconf - /Users/me/qt5/qtwebkit-examples/doc/qtwebkitexamples.qdocconf - /Users/me/qt5/qtimageformats/src/imageformats/doc/qtimageformats.qdocconf - /Users/me/qt5/qtgraphicaleffects/src/effects/doc/qtgraphicaleffects.qdocconf - /Users/me/qt5/qtscript/src/script/doc/qtscript.qdocconf - /Users/me/qt5/qtscript/src/scripttools/doc/qtscripttools.qdocconf - /Users/me/qt5/qtserialport/src/serialport/doc/qtserialport.qdocconf - /Users/me/qt5/qtdoc/doc/config/qtdoc.qdocconf - \endcode - - \section3 Why Standard Mode Is Slow - - Currently, the Qt5 build system does not use QDoc's \e {single - execution} mode for generating the Qt5 documentation. It runs QDoc - in the \e {standard} mode. The standard mode was came about - because it was the easiest way to get convert the Qt4 QDoc to - handle the modularization of Qt in Qt5. In Qt4, QDoc ran once over - all the Qt4 sources to generate the HTML documentation for Qt. - While generating the Qt documentation, Qt4 QDoc also generated an - \e {index file} for Qt. That index file was meant to be used as - input to subsequent QDoc runs for generating HTML documentation - for other software libraries/products that were based on Qt. The - Qt index file allowed QDoc to link documentation written for those - other libraries/products to the Qt4 documentation. - - When Qt5 came along, Qt was divided into modules. Since then, - many new modules have been added to Qt. As of version 5.5, there - are over 40 separate modules in Qt5, each with its own - documentation that links to (depends on) the documentation of - other Qt modules. - - In \e {standard mode}, QDoc runs twice for each module. The first - QDoc run for a particular Qt module, parses all the module's - source files and then uses the information to generate the - module's index file. It is called the \e{prepare phase} because - it \e prepares the module's index file. The second QDoc run for - the module also parses all the module's source files and then - generates the module's documentation pages. This is called the \e - {generate phase} because it generates the module's documentation. - - The module's documentation will likely contain HTML links to the - documentation of one or more of the other Qt modules. For example, - most Qt5 modules contain links to documentation in QtCore. When a - Qt module contains links into the documentation of other Qt - module's, that module is said to depend on those other Qt modules. - Hence when QDoc runs the \e {generate phase} for that module, it - must also load the index files for those modules so it can create - those thinks. - - Hence, when the Qt build system generates the Qt documentation, it - first runs QDoc once for each module to perform the \e {prepare - phase} to generate all the index files. Then it runs QDoc once for - each module to perform the \e {generate phase}, where it uses the - dependent index files to generate the module's documentation, - including any cross-module links it finds. Each execution of - QDoc, both \e {prepare phase} and \e {generate phase}, parses - all the source files that are included in the module, and in the - \e {generate phase} also parses the index files for the dependent - modules. Nothing is retained or retainable between QDoc runs. - - \section3 Why Single Execution Mode Is Much Faster - - As the name implies, single execution mode uses a single QDoc - process to generate all the Qt5 documentation. The single QDoc - process still performs a \e{prepare phase} for each module and - then a \e{generate phase} for each module, but there are a few - differences. It begins by reading the master qdocconf file. Then - it reads each qdocconf file in the master list and performs the - \e{prepare phase} for each module. During the \e{prepare phase}, - all the source files for the module are parsed to build a syntax - tree for the module. The module's index file is then generated, - although QDoc will not re-read the index files in the \e{generate - phase}. The important difference here is that the module's syntax - tree is retained after the index file is generated, so that after - the \e{prepare phase} has been run for all the modules, QDoc still - has all the syntax trees it built. - - QDoc then processes each module again for the \e{generate phase}. - But now QDoc doesn't need to re-parse each module's source files, - because the module's syntax tree is still in memory. Nor does QDoc - need to re-read the index files for the dependent modules, again - because it still has the syntax trees for those modules in memry. - It remains only to traverse each module's syntax tree to generate - the documentation pages. - - Hence, QDoc parses each source file once and only once and doesn't - need to read index files. This is what makes single execution mode - much faster than the standard mode. It is anticipated that the Qt - build system will eventually run QDoc in single execution mode. - However, changes to the master qdocconf file might be required, so - the method described above for running QDoc in single execution - mode might have to change, watch this space for updates. - - \section1 How QDoc Works - - QDoc begins by reading the configuration file you specified on the - command line. It stores all the variables from the configuration - file for later use. One of the first variables it uses is \c - {outputformats}. This variable tells QDoc which output generators - it will run. The default value is \e {HTML}, so if you don't set - \c {outputformats} in your configuration file, QDoc will generate - HTML output. That's usually what you will want anyway, but you can - also specify \e {DITAXML} to get DITA XML output instead. - - Next, QDoc uses the values of the - \l {headerdirs-variable} - {headerdirs} variable and/or the \l - {22-qdoc-configuration-generalvariables.html#headers-variable} - {headers} variable to find and parse all the header files for your - project. QDoc does \e not scan header files for QDoc comments. It - parses the header files to build a master tree of all the items - that should be documented, in other words, the items that QDoc should find - QDoc comments for. - - After parsing all the header files and building the master tree of - items to be documented, QDoc uses the value of the \l - {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} - {sourcedirs} variable and/or the value of the \l - {22-qdoc-configuration-generalvariables.html#sources-variable} - {sources} variable to find and parse all the \c {.cpp} and \c - {.qdoc} files for your project. These are the files QDoc scans for - \e {QDoc comments}. Remember that a QDoc comment begins with - an exclamation mark: \b {/*!} . - - For each QDoc comment it finds, it searches the master tree for - the item where the documentation belongs. Then it interprets the - qdoc commands in the comment and stores the interpreted commands - and the comment text in the tree node for the item. - - Finally, QDoc traverses the master tree. For each node, if the - node has stored documentation, QDoc calls the output generator - specified by the \c {outputformats} variable to format and write - the documentation in the directory specified in the configuration - file in the \l - {22-qdoc-configuration-generalvariables.html#outputdir-variable} - {outputdir} variable. - - \section1 Command Types - - QDoc interprets three types of commands: - - \list - \li \l {Topic Commands} - \li \l {Context Commands} - \li \l {Markup Commands} - \endlist - - Topic commands identify the element you are documenting, for example - a C++ class, function, type, or an extra page of text - that doesn't map to an underlying C++ element. - - Context commands tell QDoc how the element being documented - relates to other documented elements, for example, next and previous page - links, inclusion in page groups, or library modules. Context - commands can also provide information about the documented element - that QDoc can't get from the source files, for example, whether the - element is thread-safe, whether it is an overloaded or reimplemented function, - or whether it has been deprecated. - - Markup commands tell QDoc how text and image elements in the - document should be rendered, or about the document's outline - structure. -*/ - diff --git a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc b/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc deleted file mode 100644 index 49cbfc0654..0000000000 --- a/src/tools/qdoc/doc/qdoc-manual-markupcmds.qdoc +++ /dev/null @@ -1,4081 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2015 The Qt Company Ltd. -** Contact: http://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see http://www.qt.io/terms-conditions. For further -** information use the contact form at http://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \page 03-qdoc-commands-markup.html - \contentspage QDoc Manual - \previouspage Naming Things - \nextpage Text Markup - - \title Markup Commands - - The markup commands indicate the generated documentation's visual - appearance and logical structure. - - \list - \li \l {a-command} {\\a} - \li \l {annotatedlist-command} {\\annotatedlist} - \li \l {b-command} {\\b} \span {class="newStuff"} - \li \l {b-command} {\\bold} {(deprecated, use \\b)} - \li \l {brief-command} {\\brief} - \li \l {c-command} {\\c} - \li \l {caption-command} {\\caption} - \li \l {chapter-command} {\\chapter} - \li \l {code-command} {\\code} - \li \l {codeline-command} {\\codeline} - \li \l {div-command} {\\div} - \li \l {dots-command} {\\dots} - \li \l {e-command} {\\e} \span {class="newStuff"} - \li \l {else-command} {\\else} - \li \l {endif-command} {\\endif} - \li \l {footnote-command} {\\footnote} - \li \l {generatelist-command} {\\generatelist} - \li \l {header-command} {\\header} - \li \l {e-command} {\\i} \span {class="newStuff"} {(deprecated, use \\e)} - \li \l {if-command} {\\if} - \li \l {image-command} {\\image} - \li \l {include-command} {\\include} - \li \l {include-command} {\\input} - \li \l {inlineimage-command} {\\inlineimage} - \li \l {keyword-command} {\\keyword} - \li \l {l-command} {\\l} - \li \l {legalese-command} {\\legalese} - \li \l {li-command} {\\li} \span {class="newStuff"} - \li \l {list-command} {\\list} - \li \l {meta-command} {\\meta} - \li \l {noautolist-command} {\\noautolist} - \li \l {newcode-command} {\\newcode} - \li \l {li-command} {\\o} \span {class="newStuff"} {(deprecated, use \\li)} - \li \l {note-command} {\\note} - \li \l {oldcode-command} {\\oldcode} - \li \l {omit-command} {\\omit} - \li \l {part-command} {\\part} - \li \l {printline-command} {\\printline} - \li \l {printto-command} {\\printto} - \li \l {printuntil-command} {\\printuntil} - \li \l {quotation-command} {\\quotation} - \li \l {quotefile-command} {\\quotefile} - \li \l {quotefromfile-command} {\\quotefromfile} - \li \l {raw-command} {\\raw} - \li \l {row-command} {\\row} - \li \l {sa-command} {\\sa} - \li \l {sectionOne-command} {\\section1} - \li \l {sectionTwo-command} {\\section2} - \li \l {sectionThree-command} {\\section3} - \li \l {sectionFour-command} {\\section4} - \li \l {skipline-command} {\\skipline} - \li \l {skipto-command} {\\skipto} - \li \l {skipuntil-command} {\\skipuntil} - \li \l {snippet-command} {\\snippet} - \li \l {span-command} {\\span} - \li \l {sub-command} {\\sub} - \li \l {sup-command} {\\sup} - \li \l {table-command} {\\table} - \li \l {tableofcontents-command} {\\tableofcontents} - \li \l {target-command} {\\target} - \li \l {tt-command} {\\tt} - \li \l {uicontrol-command} {\\uicontrol} {(new 25/3/2012)} - \li \l {underline-command} {\\underline} - \li \l {raw-command} {\\unicode} - \li \l {warning-command} {\\warning} - \li \l {backslash-command} {\\\\} - \endlist -*/ - - -/*! - \page 04-qdoc-commands-textmarkup.html - \contentspage QDoc Manual - \previouspage Markup Commands - \nextpage Document Structure - - \title Text Markup - - The text formatting commands indicate how text is to be rendered. - - \target a-command - \section1 \\a (parameter marker) - - The \\a command tells QDoc the next word is a formal parameter name. - - A warning is emitted when a formal parameter is not documented or - is misspelled, so when you document a function you should mention - each formal parameter by name in the function description, - preceded by the \\a command. The parameter name is then rendered - in italics. - - \code - / *! - Constructs a line edit containing the text - \a contents. The \a parent parameter is sent - to the QWidget constructor. - * / - - QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent) - { - ... - } - - \endcode - - QDoc renders this as: - - \quotation - \b {QLineEdit::QLineEdit ( const QString & - contents, QWidget *parent )} - - Constructs a line edit containing the text \a contents. - The \a parent parameter is sent to the QWidget constructor. - \endquotation - - The formal parameter name may be enclosed between curly brackets, - but that isn't required. - - \target c-command - \section1 \\c (code font) - - The \\c command is used for rendering variable names, user-defined - class names, and C++ keywords (for example, \c int and \c for) in the code - font. - - The command renders its argument using a monospace font. For - example: - - \code - / *! - The \c AnalogClock class provides a clock widget with hour - and minute hands that is automatically updated every - few seconds. - * / - \endcode - - QDoc renders this as: - - \quotation - The \c AnalogClock class provides a clock widget with hour - and minute hands, which are automatically updated every - few seconds. - \endquotation - - If the text to be rendered in the code font contains spaces, enclose the - entire text in curly brackets. - - \code - \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} - \endcode - - QDoc renders this as: - - \quotation - \c {QLineEdit::QLineEdit(const QString &contents, QWidget *parent) :QWidget(parent)} - \endquotation - - The \\c command accepts the special character \c \ within its - argument, which renders it as a normal character. So if you want - to use nested commands, you must use the \l {tt-command} {teletype - (\\tt)} command instead. - - See also \l {tt-command} {\\tt} and \l {code-command} {\\code}. - - \target div-command - \section1 \\div - - The \\div and \\enddiv commands delimit a large or small block of - text (which may include other QDoc commands) to which special - formatting attributes should be applied. - - An argument must be provided in curly braces, as in the qdoc - comment shown below. The argument is not interpreted but is used - as attribute(s) of the tag that is output by qdoc. - - For example, we might want to render an inline image so that it - floats to the right of the current block of text: - - \code - / *! - \div {class="float-right"} - \inlineimage qml-column.png - \enddiv - - * / - \endcode - - If qdoc is generating HTML, it will translate these commands to: - - \code - <div class="float-right"><p><img src="images/qml-column.png" /></p></div> - \endcode - - For HTML, the attribute value \e {float-right} then will refer to - a clause in the style.css file, which in this case could be: - - \code - div.float-right - { - float: right; margin-left: 2em - } - \endcode - - If qdoc is generating DITA XML, it will translate the commands to: - - \code - <sectiondiv outputclass="float-right"> - <p> - <fig> - <image href="images/qml-column.png" placement="inline"/> - </fig> - </p> - </sectiondiv> - \endcode - - Your DITA XML publishing program must then recognize the \e - {outputclass} attribute value. - - \note Note that the \b {\\div} command can be nested. - - Below you can find an example taken from the index.qdoc file used to - generate index.html for Qt 4.7: - - \code - \div {class="indexbox guide"} - \div {class="heading"} - Qt Developer Guide - \enddiv - \div {class="indexboxcont indexboxbar"} - \div {class="section indexIcon"} \emptyspan - \enddiv - \div {class="section"} - Qt is a cross-platform application and UI - framework. Using Qt, you can write web-enabled - applications once and deploy them across desktop, - mobile and embedded operating systems without - rewriting the source code. - \enddiv - \div {class="section sectionlist"} - \list - \li \l{Getting Started} - \li \l{Installation} {Installation} - \li \l{how-to-learn-qt.html} {How to learn Qt} - \li \l{tutorials.html} {Tutorials} - \li \l{Qt Examples} {Examples} - \li \l{qt4-7-intro.html} {What's new in Qt 4.7} - \endlist - \enddiv - \enddiv - \enddiv - \endcode - - When all the class attribute values are defined as they are in the - style.css file that is used for rendering the Qt documentation, - the above example is rendered as: - - \div {class="indexbox guide"} - \div {class="heading"} - Qt Developer Guide - \enddiv - \div {class="indexboxcont indexboxbar"} - \div {class="section indexIcon"} \emptyspan - \enddiv - \div {class="section"} - Qt is a cross-platform application and UI - framework. Using Qt, you can write web-enabled - applications once and deploy them across desktop, - mobile and embedded operating systems without - rewriting the source code. - \enddiv - \div {class="section sectionlist"} - \list - \li Getting Started - \li Installation |