#include <webxmlgenerator.h>

Inheritance diagram for WebXMLGenerator:

Collaboration diagram for WebXMLGenerator:

Public Member Functions
	WebXMLGenerator (FileResolver &file_resolver)

void	initializeGenerator () override
	Initializes the HTML output generator's data structures from the configuration (Config) singleton.

void	terminateGenerator () override
	Gracefully terminates the HTML output generator.

QString	format () override

void	append (QXmlStreamWriter &writer, Node *node) override

Public Member Functions inherited from HtmlGenerator
	HtmlGenerator (FileResolver &file_resolver)

	~HtmlGenerator () override
	Destroys the HTML output generator.

void	generateDocs () override
	If qdoc is in the `{-prepare}` phase, traverse the primary tree to generate the index file for the current module.

QString	protectEnc (const QString &string)

Public Member Functions inherited from XmlGenerator
	XmlGenerator (FileResolver &file_resolver)

Public Member Functions inherited from Generator
	Generator (Moc moc, ClassDef classDef, const QList< QByteArray > &metaTypes, const QHash< QByteArray, QByteArray > &knownQObjectClasses, const QHash< QByteArray, QByteArray > &knownGadgets, FILE *outfile=nullptr, bool requireCompleteTypes=false)

void	generateCode ()

qsizetype	registeredStringsCount ()

	Generator (FileResolver &file_resolver)
	Constructs the generator base class.

virtual	~Generator ()
	Destroys the generator after removing it from the list of output generators.

virtual bool	canHandleFormat (const QString &format)

virtual void	initializeFormat ()
	Reads format-specific variables from config, sets output (sub)directories, creates them on the filesystem and copies the template-specific files.

virtual QString	typeString (const Node *node)

QString	fullDocumentLocation (const Node *node)
	Returns the full document location.

QString	linkForExampleFile (const QString &path, const QString &fileExt=QString())
	Constructs an href link from an example file name, which is a path to the example file.

Public Member Functions inherited from IndexSectionWriter
virtual	~IndexSectionWriter ()=default

Protected Member Functions
qsizetype	generateAtom (const Atom atom, const Node relative, CodeMarker *marker) override
	Most of the output is generated by QDocIndexFiles and the append() callback.

void	generateCppReferencePage (Aggregate aggregate, CodeMarker marker) override
	Generate a reference page for the C++ class, namespace, or header file documented in node using the code marker provided.

void	generatePageNode (PageNode pn, CodeMarker marker) override
	Generate the HTML page for an entity that doesn't map to any underlying parsable C++ or QML element.

void	generateDocumentation (Node *node) override
	Recursive writing of HTML files from the root node.

void	generateExampleFilePage (const Node en, ResolvedFile file, CodeMarker marker=nullptr) override
	Generate an html file with the contents of a C++ or QML source file.

QString	fileExtension () const override
	Returns "html" for this subclass of Generator.

virtual const Atom *	addAtomElements (QXmlStreamWriter &writer, const Atom atom, const Node relative, CodeMarker *marker)

virtual void	generateIndexSections (QXmlStreamWriter &writer, Node *node)

Protected Member Functions inherited from HtmlGenerator
void	generateProxyPage (Aggregate aggregate, CodeMarker marker) override

void	generateQmlTypePage (QmlTypeNode qcn, CodeMarker marker) override
	Generate the HTML page for a QML type.

void	generateCollectionNode (CollectionNode cn, CodeMarker marker) override
	Generate the HTML page for a group, module, or QML module.

void	generateGenericCollectionPage (CollectionNode cn, CodeMarker marker) override
	Generate the HTML page for a generic collection.

Protected Member Functions inherited from XmlGenerator
QString	registerRef (const QString &ref, bool xmlCompliant=false)
	Registers an anchor reference and returns a unique and cleaned copy of the reference (the one that should be used in the output).

QString	refForNode (const Node *node)
	Generates a clean and unique reference for the given node.

QString	linkForNode (const Node node, const Node relative)
	Construct the link string for the node and return it.

QString	getLink (const Atom atom, const Node relative, const Node **node)
	This function is called for links, i.e.

QString	getAutoLink (const Atom atom, const Node relative, const Node **node, Node::Genus=Node::DontCare)
	This function is called for autolinks, i.e.

std::pair< QString, QString >	anchorForNode (const Node *node)

Protected Member Functions inherited from Generator
void	beginSubPage (const Node *node, const QString &fileName)
	Creates the file named fileName in the output directory.

void	endSubPage ()
	Flush the text stream associated with the subpage, and then pop it off the text stream stack and delete it.

virtual void	generateAlsoList (const Node node, CodeMarker marker)

virtual void	generateAlsoList (const Node *node)

virtual void	generateBody (const Node node, CodeMarker marker)
	Generate the body of the documentation from the qdoc comment found with the entity represented by the node.

virtual bool	generateText (const Text &text, const Node relative, CodeMarker marker)
	Generate the documentation for relative.

virtual bool	generateText (const Text &text, const Node *relative)

virtual int	skipAtoms (const Atom *atom, Atom::AtomType type) const

void	initializeTextOutput ()
	Resets the variables used during text output.

QString	fileName (const Node *node, const QString &extension=QString()) const
	If the node has a URL, return the URL as the file name.

QMap< QString, QString > &	formattingLeftMap ()

QMap< QString, QString > &	formattingRightMap ()

const Atom *	generateAtomList (const Atom atom, const Node relative, CodeMarker *marker, bool generate, int &numGeneratedAtoms)

void	generateEnumValuesForQmlProperty (const Node node, CodeMarker marker)

void	generateRequiredLinks (const Node node, CodeMarker marker)
	Generates either a link to the project folder for example node, or a list of links files/images if 'url.examples config' variable is not defined.

void	generateLinkToExample (const ExampleNode en, CodeMarker marker, const QString &exampleUrl)
	Generates an external link to the project folder for example node.

virtual void	generateFileList (const ExampleNode en, CodeMarker marker, bool images)
	This function is called when the documentation for an example is being formatted.

void	generateSince (const Node node, CodeMarker marker)

void	generateNoexceptNote (const Node node, CodeMarker marker)

void	generateStatus (const Node node, CodeMarker marker)

virtual void	generateAddendum (const Node node, Addendum type, CodeMarker marker, bool generateNote)
	Generates an addendum note of type type for node, using marker as the code marker.

virtual void	generateAddendum (const Node node, Addendum type, CodeMarker marker)

void	generateThreadSafeness (const Node node, CodeMarker marker)
	Generates text that explains how threadsafe and/or reentrant node is.

bool	generateComparisonCategory (const Node node, CodeMarker marker=nullptr)

bool	generateComparisonList (const Node *node)
	Generates a list of types that compare to node with the comparison category that applies for the relationship, followed by (an optional) descriptive text.

void	generateOverloadedSignal (const Node node, CodeMarker marker)
	If the node is an overloaded signal, add a node with an example on how to connect to it.

QString	indent (int level, const QString &markedCode)

QTextStream &	out ()

QString	outFileName ()

bool	parseArg (const QString &src, const QString &tag, int pos, int n, QStringView contents, QStringView *par1=nullptr)

void	unknownAtom (const Atom *atom)

int	appendSortedQmlNames (Text &text, const Node *base, const QStringList &knownTypes, const NodeList &subs)

void	appendFullName (Text &text, const Node apparentNode, const Node relative, const Node *actualNode=nullptr)

void	appendFullName (Text &text, const Node apparentNode, const QString &fullName, const Node actualNode)

int	appendSortedNames (Text &text, const ClassNode *classe, const QList< RelatedClass > &classes)

void	appendSignature (Text &text, const Node *node)
	Append the signature for the function named in node to text, so that is a link to the documentation for that function.

void	signatureList (const NodeList &nodes, const Node relative, CodeMarker marker)
	Generate a bullet list of function signatures.

void	addImageToCopy (const ExampleNode *en, const ResolvedFile &resolved_file)

Private Member Functions
QString	fileBase (const Node *node) const override

Additional Inherited Members
Public Types inherited from Generator
enum	ListType { Generic , Obsolete }

enum	Addendum { Invokable , PrivateSignal , QmlSignalHandler , AssociatedProperties , BindableProperty }

Static Public Member Functions inherited from HtmlGenerator
static QString	protect (const QString &string)

Static Public Member Functions inherited from Generator
static QString	exampleFileTitle (const ExampleNode *relative, const QString &fileName)
	Helper function to construct a title for a file or image page included in an example.

static Generator *	currentGenerator ()

static Generator *	generatorForFormat (const QString &format)

static void	initialize ()

static const QString &	outputDir ()

static const QString &	outputSubdir ()

static void	terminate ()

static const QStringList &	outputFileNames ()

static bool	noLinkErrors ()

static bool	autolinkErrors ()

static QString	defaultModuleName ()

static void	resetUseOutputSubdirs ()

static bool	useOutputSubdirs ()

static void	setQmlTypeContext (QmlTypeNode *t)

static QmlTypeNode *	qmlTypeContext ()

static QString	cleanRef (const QString &ref, bool xmlCompliant=false)
	Clean the given ref to be used as an HTML anchor or an `xml:id`.

static QString	plainCode (const QString &markedCode)

Static Protected Member Functions inherited from XmlGenerator
static bool	hasBrief (const Node *node)
	Do not display.

static bool	isThreeColumnEnumValueTable (const Atom *atom)
	Determines whether the list atom should be shown with three columns (constant-value-description).

static bool	isOneColumnValueTable (const Atom *atom)
	Determines whether the list atom should be shown with just one column (value).

static int	hOffset (const Node *node)
	Header offset depending on the type of the node.

static void	rewritePropertyBrief (const Atom atom, const Node relative)
	Rewrites the brief of this node depending on its first word.

static Node::NodeType	typeFromString (const Atom *atom)
	Returns the type of this atom as an enumeration.

static void	setImageFileName (const Node *relative, const QString &fileName)
	For images shown in examples, set the image file to the one it will have once the documentation is generated.

static std::pair< QString, int >	getAtomListValue (const Atom *atom)
	Handles the differences in lists between list tags and since tags, and returns the content of the list entry atom (first member of the pair).

static std::pair< QString, QString >	getTableWidthAttr (const Atom *atom)
	Parses the table attributes from the given atom.

static QString	targetType (const Node *node)
	Returns a string describing the node type.

Static Protected Member Functions inherited from Generator
static QFile *	openSubPageFile (const PageNode *node, const QString &fileName)
	Creates the file named fileName in the output directory and returns a QFile pointing to this file.

static bool	matchAhead (const Atom *atom, Atom::AtomType expectedAtomType)

static QString	outputPrefix (const Node *node)

static QString	outputSuffix (const Node *node)

static void	supplementAlsoList (const Node *node, QList< Text > &alsoList)

static QString	trimmedTrailing (const QString &string, const QString &prefix, const QString &suffix)
	Trims trailing whitespace off the string and returns the trimmed string.

static QString	formatSince (const Node *node)

static QString	getOverloadedSignalCode (const Node *node)
	Returns the string containing an example code of the input node, if it is an overloaded signal.

static bool	hasExceptions (const Node *node, NodeList &reentrant, NodeList &threadsafe, NodeList &nonreentrant)

static bool	comparePaths (const QString &a, const QString &b)

static bool	appendTrademark (const Atom *atom)
	Returns `true` if a trademark symbol should be appended to the output as determined by atom.

static std::optional< std::pair< QString, QString > >	cmakeRequisite (const CollectionNode *cn)
	Generate the CMake requisite for the node cn, i.e.

static Qt::SortOrder	sortOrder (const QString &str)

Protected Attributes inherited from XmlGenerator
QHash< QString, QString >	refMap

const Node *	m_linkNode { nullptr }

Protected Attributes inherited from Generator
QString	naturalLanguage

QString	tagFile_

QStack< QTextStream * >	outStreamStack

FileResolver &	file_resolver

QDocDatabase *	m_qdb { nullptr }

bool	m_inLink { false }

bool	m_inContents { false }

bool	m_inSectionHeading { false }

bool	m_inTableHeader { false }

bool	m_threeColumnEnumValueTable { true }

bool	m_showInternal { false }

bool	m_quoting { false }

int	m_numTableRows { 0 }

QString	m_link {}

QString	m_sectionNumber {}

Static Protected Attributes inherited from XmlGenerator
static const QRegularExpression	m_funcLeftParen

Detailed Description

Definition at line 18 of file webxmlgenerator.h.

Constructor & Destructor Documentation

◆ WebXMLGenerator()

WebXMLGenerator::WebXMLGenerator ( FileResolver & file_resolver )

Definition at line 24 of file webxmlgenerator.cpp.

References HtmlGenerator::HtmlGenerator().

Referenced by processQdocconfFile().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Function Documentation

◆ addAtomElements()

const Atom * WebXMLGenerator::addAtomElements	(	QXmlStreamWriter &	writer,
		const Atom *	atom,
		const Node *	relative,
		CodeMarker *	marker )

protectedvirtual

Definition at line 264 of file webxmlgenerator.cpp.

References Atom::AnnotatedList, Generator::appendTrademark(), Atom::AutoLink, Atom::BaseName, Atom::BriefLeft, Atom::BriefRight, Atom::C, Atom::CaptionLeft, Atom::CaptionRight, Atom::Code, Atom::CodeBad, Atom::CodeQuoteArgument, Atom::CodeQuoteCommand, Node< _Tp >::doc(), Atom::ExampleFileLink, Atom::ExampleImageLink, Generator::file_resolver, Atom::FootnoteLeft, Atom::FootnoteRight, Atom::FormatEndif, Atom::FormatIf, Atom::FormattingLeft, Atom::FormattingRight, Atom::GeneratedList, Node< _Tp >::Group, Atom::Image, Atom::ImageText, Atom::ImportantLeft, Atom::ImportantRight, Atom::InlineImage, Node< _Tp >::isDeprecated(), Node< _Tp >::isEnumType(), Node< _Tp >::isProperty(), Node< _Tp >::isVariable(), Atom::LegaleseLeft, Atom::LegaleseRight, Atom::Link, Atom::LinkNode, Atom::ListItemLeft, Atom::ListItemNumber, Atom::ListItemRight, Atom::ListLeft, Atom::ListRight, Atom::ListTagLeft, Atom::ListTagRight, Doc::location(), Node< _Tp >::location(), Generator::m_inLink, Generator::m_inSectionHeading, Generator::m_qdb, Generator::m_quoting, CollectionNode::members(), Atom::next(), Node< _Tp >::nodeType(), Atom::Nop, Atom::NoteLeft, Atom::NoteRight, Atom::ParaLeft, Atom::ParaRight, Node< _Tp >::parent(), Node< _Tp >::Property, Atom::QuotationLeft, Atom::QuotationRight, Atom::RawString, Text::sectionHeading(), Atom::SectionHeadingLeft, Atom::SectionHeadingRight, Atom::SectionLeft, Atom::SectionRight, Atom::SidebarLeft, Atom::SidebarRight, Atom::SnippetCommand, Atom::SnippetIdentifier, Atom::SnippetLocation, Atom::String, Atom::TableHeaderLeft, Atom::TableHeaderRight, Atom::TableItemLeft, Atom::TableItemRight, Atom::TableLeft, Atom::TableRight, Atom::TableRowLeft, Atom::TableRowRight, Atom::Target, Atom::type(), Atom::UnhandledFormat, Atom::UnknownCommand, Node< _Tp >::Variable, Atom::WarningLeft, and Atom::WarningRight.

Referenced by append().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ append()

void WebXMLGenerator::append	(	QXmlStreamWriter &	writer,
		Node *	node )

overridevirtual

Implements IndexSectionWriter.

Definition at line 156 of file webxmlgenerator.cpp.

References addAtomElements(), Doc::body(), Node< _Tp >::doc(), Text::firstAtom(), Generator::generateRequiredLinks(), CollectionNode::getMembers(), CollectionNode::hasClasses(), CollectionNode::hasNamespaces(), Node< _Tp >::isClassNode(), Node< _Tp >::isExample(), Node< _Tp >::isGroup(), Node< _Tp >::isModule(), Node< _Tp >::isTextPageNode(), Doc::location(), Generator::m_inLink, Generator::m_inSectionHeading, marker_, CollectionNode::members(), Node< _Tp >::Namespace, and PageNode::noAutoList().

Here is the call graph for this function:

◆ fileBase()

QString WebXMLGenerator::fileBase ( const Node * node ) const

overrideprivatevirtual

Reimplemented from HtmlGenerator.

Definition at line 898 of file webxmlgenerator.cpp.

◆ fileExtension()

QString WebXMLGenerator::fileExtension ( ) const

nodiscardoverrideprotectedvirtual

Returns "html" for this subclass of Generator.

Reimplemented from HtmlGenerator.

Definition at line 41 of file webxmlgenerator.cpp.

◆ format()

QString WebXMLGenerator::format ( )

overridevirtual

Reimplemented from HtmlGenerator.

Definition at line 36 of file webxmlgenerator.cpp.

◆ generateAtom()

qsizetype WebXMLGenerator::generateAtom	(	const Atom *	atom,
		const Node *	relative,
		CodeMarker *	marker )

overrideprotectedvirtual

Most of the output is generated by QDocIndexFiles and the append() callback.

Some pages produce supplementary output while being generated, and that's handled here.

Reimplemented from HtmlGenerator.

Definition at line 55 of file webxmlgenerator.cpp.

◆ generateCppReferencePage()

void WebXMLGenerator::generateCppReferencePage	(	Aggregate *	aggregate,
		CodeMarker *	marker )

overrideprotectedvirtual

Generate a reference page for the C++ class, namespace, or header file documented in node using the code marker provided.

Reimplemented from HtmlGenerator.

Definition at line 62 of file webxmlgenerator.cpp.

References Generator::endSubPage(), and generateIndexSections().

Referenced by generateDocumentation().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ generateDocumentation()

void WebXMLGenerator::generateDocumentation ( Node * node )

overrideprotectedvirtual

Recursive writing of HTML files from the root node.

Reimplemented from Generator.

Definition at line 230 of file webxmlgenerator.cpp.

References generateCppReferencePage(), generatePageNode(), Node< _Tp >::isAggregate(), Node< _Tp >::isClassNode(), Node< _Tp >::isCollectionNode(), Node< _Tp >::isExternalPage(), Node< _Tp >::isHeader(), Node< _Tp >::isIndexNode(), Node< _Tp >::isInternal(), Node< _Tp >::isNamespace(), Node< _Tp >::isTextPageNode(), Generator::m_qdb, Generator::m_showInternal, QDocDatabase::mergeCollections(), Node< _Tp >::parent(), and Node< _Tp >::wasSeen().

Here is the call graph for this function:

◆ generateExampleFilePage()

void WebXMLGenerator::generateExampleFilePage	(	const Node *	en,
		ResolvedFile	resolved_file,
		CodeMarker *	marker = nullptr )

overrideprotectedvirtual

Generate an html file with the contents of a C++ or QML source file.

Reimplemented from HtmlGenerator.

Definition at line 102 of file webxmlgenerator.cpp.

References Node< _Tp >::doc(), Generator::endSubPage(), Doc::location(), Node< _Tp >::location(), and Doc::quoteFromFile().

Here is the call graph for this function:

◆ generateIndexSections()

void WebXMLGenerator::generateIndexSections	(	QXmlStreamWriter &	writer,
		Node *	node )

protectedvirtual

Definition at line 143 of file webxmlgenerator.cpp.

References Node< _Tp >::isGroup(), Node< _Tp >::location(), and marker_.

Referenced by generateCppReferencePage().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ generatePageNode()

void WebXMLGenerator::generatePageNode	(	PageNode *	pn,
		CodeMarker *	marker )

overrideprotectedvirtual

Generate the HTML page for an entity that doesn't map to any underlying parsable C++ or QML element.

Reimplemented from HtmlGenerator.

Definition at line 82 of file webxmlgenerator.cpp.

References Generator::endSubPage().

Referenced by generateDocumentation().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ initializeGenerator()

void WebXMLGenerator::initializeGenerator ( )

overridevirtual

Initializes the HTML output generator's data structures from the configuration (Config) singleton.

Reimplemented from HtmlGenerator.

Definition at line 26 of file webxmlgenerator.cpp.

References HtmlGenerator::initializeGenerator().

Here is the call graph for this function:

◆ terminateGenerator()

void WebXMLGenerator::terminateGenerator ( )

overridevirtual

Gracefully terminates the HTML output generator.

Reimplemented from HtmlGenerator.

Definition at line 31 of file webxmlgenerator.cpp.

References HtmlGenerator::terminateGenerator().

Here is the call graph for this function:

The documentation for this class was generated from the following files:

qttools/src/qdoc/qdoc/src/qdoc/webxmlgenerator.h (5212645b4665917019a96ba873d9e98c1a136b5f)
qttools/src/qdoc/qdoc/src/qdoc/webxmlgenerator.cpp (10a1d2658b59c9fd32209aaf59257c7974f56125)

Public Member Functions

Protected Member Functions

Private Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ WebXMLGenerator()

Member Function Documentation

◆ addAtomElements()

◆ append()

◆ fileBase()

◆ fileExtension()

◆ format()

◆ generateAtom()

◆ generateCppReferencePage()

◆ generateDocumentation()

◆ generateExampleFilePage()

◆ generateIndexSections()

◆ generatePageNode()

◆ initializeGenerator()

◆ terminateGenerator()