Generates documentation using external templates and a pre-built IR. More...

#include <templategenerator.h>

Inheritance diagram for TemplateGenerator:

Collaboration diagram for TemplateGenerator:

Public Member Functions
	TemplateGenerator (FileResolver &file_resolver)
	~TemplateGenerator () override=default
void	initializeGenerator () override
	No-op base implementation.
void	terminateGenerator () override
QString	format () const override
	Returns the format identifier for this producer (e.g., "HTML", "DocBook", "template").
void	generateDocs () override
	Traverses the database recursively to generate all the documentation.
Public Member Functions inherited from Generator
qreal	snippets_4_to_11 (int z, quint32 begin, quint32 end, const quint32 *seedBuffer, size_t len)
	Generator (Moc moc, const ClassDef classDef, const QList< QByteArray > &metaTypes, const QHash< QByteArray, QByteArray > &knownQObjectClasses, const QHash< QByteArray, QByteArray > &knownGadgets, const QHash< QByteArray, QByteArray > &hashes, 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.
void	prepare () override
	Prepares the producer for an output run.
void	produce () override
	Produces documentation output.
void	finalize () override
	Finalizes output production.
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, bool plural=false)
QString	fullDocumentLocation (const Node *node) const
	Returns the full document location.
QString	linkForExampleFile (const QString &path, const QString &fileExt=QString()) const
	Constructs an href link from an example file name, which is a path to the example file.
virtual QString	fileBase (const Node *node) const
qreal	snippets_4_to_11 (int z, quint32 begin, quint32 end, const quint32 *seedBuffer, size_t len)
Public Member Functions inherited from QRandomGenerator
	QRandomGenerator (quint32 seedValue=1)
	Initializes this QRandomGenerator object with the value seedValue as the seed.
template<qsizetype N>
	QRandomGenerator (const quint32(&seedBuffer)[N])
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Initializes this QRandomGenerator object with the values found in the array seedBuffer as the seed.
	QRandomGenerator (const quint32 *seedBuffer, qsizetype len)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Initializes this QRandomGenerator object with len values found in the array seedBuffer as the seed.
Q_CORE_EXPORT	QRandomGenerator (std::seed_seq &sseq) noexcept
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Initializes this QRandomGenerator object with the seed sequence sseq as the seed.
Q_CORE_EXPORT	QRandomGenerator (const quint32 begin, const quint32 end)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Initializes this QRandomGenerator object with the values found in the range from begin to end as the seed.
Q_CORE_EXPORT	QRandomGenerator (const QRandomGenerator &other)
	Creates a copy of the generator state in the other object.
Q_CORE_EXPORT QRandomGenerator &	operator= (const QRandomGenerator &other)
	~QRandomGenerator ()=default
quint32	generate ()
	Generates a 32-bit random quantity and returns it.
quint64	generate64 ()
	Generates a 64-bit random quantity and returns it.
double	generateDouble ()
	Generates one random qreal in the canonical range [0, 1) (that is, inclusive of zero and exclusive of 1).
double	bounded (double highest)
	Generates one random double in the range between 0 (inclusive) and highest (exclusive).
quint32	bounded (quint32 highest)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Generates one random 32-bit quantity in the range between 0 (inclusive) and highest (exclusive).
quint32	bounded (quint32 lowest, quint32 highest)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Generates one random 32-bit quantity in the range between lowest (inclusive) and highest (exclusive).
int	bounded (int highest)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Generates one random 32-bit quantity in the range between 0 (inclusive) and highest (exclusive).
int	bounded (int lowest, int highest)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Generates one random 32-bit quantity in the range between lowest (inclusive) and highest (exclusive), both of which may be negative, but highest must be greater than lowest.
quint64	bounded (quint64 highest)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Generates one random 64-bit quantity in the range between 0 (inclusive) and highest (exclusive).
quint64	bounded (quint64 lowest, quint64 highest)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Generates one random 64-bit quantity in the range between lowest (inclusive) and highest (exclusive).
qint64	bounded (qint64 highest)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Generates one random 64-bit quantity in the range between 0 (inclusive) and highest (exclusive).
qint64	bounded (qint64 lowest, qint64 highest)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Generates one random 64-bit quantity in the range between lowest (inclusive) and highest (exclusive), both of which may be negative, but highest must be greater than lowest.
qint64	bounded (int lowest, qint64 highest)
qint64	bounded (qint64 lowest, int highest)
quint64	bounded (unsigned lowest, quint64 highest)
quint64	bounded (quint64 lowest, unsigned highest)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.This function exists to help with overload resolution when the types of the parameters don't exactly match.
template<typename UInt, IfValidUInt< UInt > = true>
void	fillRange (UInt *buffer, qsizetype count)
	Generates count 32- or 64-bit quantities (depending on the type `UInt`) and stores them in the buffer pointed by buffer.
template<typename UInt, size_t N, IfValidUInt< UInt > = true>
void	fillRange (UInt(&buffer)[N])
	Generates N 32-bit or 64-bit quantities (depending on the type `UInt`) and stores them in the buffer array.
template<typename ForwardIterator>
void	generate (ForwardIterator begin, ForwardIterator end)
	Generates 32-bit quantities and stores them in the range between begin and end.
void	generate (quint32 begin, quint32 end)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
result_type	operator() ()
	Generates a 32-bit random quantity and returns it.
void	seed (quint32 s=1)
	Reseeds this object using the value seed as the seed.
void	seed (std::seed_seq &sseq) noexcept
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Reseeds this object using the seed sequence seed as the seed.
Q_CORE_EXPORT void	discard (unsigned long long z)
	Discards the next z entries from the sequence.
Public Member Functions inherited from IOutputProducer
virtual	~IOutputProducer ()=default

Protected Member Functions
QString	fileExtension () const override
void	generateCppReferencePage (Aggregate aggregate, CodeMarker marker) override
void	generateQmlTypePage (QmlTypeNode qcn, CodeMarker marker) override
void	generatePageNode (PageNode pn, CodeMarker marker) override
void	generateCollectionNode (CollectionNode cn, CodeMarker marker) override
qsizetype	generateAtom (const Atom atom, const Node relative, CodeMarker *marker) override
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	generateExampleFilePage (const Node , ResolvedFile, CodeMarker =nullptr)
virtual void	generateAlsoList (const Node node, CodeMarker marker)
	Generates text for a "see also" list for the given node and marker if a list has been defined.
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 void	generateProxyPage (Aggregate , CodeMarker )
virtual void	generateGenericCollectionPage (CollectionNode , CodeMarker )
virtual void	generateDocumentation (Node *node)
	Recursive writing of HTML files from the root 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	generateEnumValuesForQmlReference (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, AdmonitionPrefix prefix)
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	generateComparisonTable (const Node *node)
	Generates a table of comparison categories for node, combining both self-comparison (from \compares) and comparisons with other types (from \compareswith).
QString	generateOverloadSnippet (const FunctionNode *func)
	Generates a contextual code snippet for connecting to an overloaded signal or slot.
QString	generateObjectName (const QString &className)
	Generates an appropriate object name for code snippets based on the class name.
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 QList< Node > &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 QList< Node * > &nodes, const Node relative, CodeMarker marker)
	Generate a bullet list of function signatures.
void	addImageToCopy (const ExampleNode *en, const ResolvedFile &resolved_file)
Protected Member Functions inherited from QRandomGenerator
	QRandomGenerator (System)

Additional Inherited Members
Public Types inherited from Generator
enum	ListType { Generic , Obsolete }
enum	Addendum { Invokable , PrivateSignal , QmlSignalHandler , AssociatedProperties , BindableProperty , OverloadNote }
enum class	AdmonitionPrefix : unsigned char { None , Note }
Public Types inherited from QRandomGenerator
typedef quint32	result_type
	A typedef to the type that operator() returns.
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 void	setCurrentGenerator (Generator *generator)
static Generator *	generatorForFormat (const QString &format)
static void	initialize ()
static const QString &	outputDir ()
static const QString &	outputSubdir ()
static const QString &	imagesOutputDir ()
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 Qt::SortOrder	sortOrder (const QString &str)
static void	addNodeLink (Text &text, const QString &nodeRef, const QString &linkText)
	Adds a formatted link to the specified text stream.
static void	addNodeLink (Text &text, const INode *node, const QString &linkText=QString())
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.This convenience overload automatically obtains the node reference string using stringForNode().
Static Public Member Functions inherited from QRandomGenerator
static constexpr result_type	min ()
	Returns the minimum value that QRandomGenerator may ever generate.
static constexpr result_type	max ()
	Returns the maximum value that QRandomGenerator may ever generate.
static Q_DECL_CONST_FUNCTION QRandomGenerator *	system ()
	\threadsafe
static Q_DECL_CONST_FUNCTION QRandomGenerator *	global ()
	\threadsafe
static QRandomGenerator	securelySeeded ()
	Returns a new QRandomGenerator object that was securely seeded with QRandomGenerator::system().
Protected Types inherited from QRandomGenerator
enum	System
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 bool	hasExceptions (const Node node, QList< Node > &reentrant, QList< Node * > &threadsafe, QList< Node * > &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.
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_quoting { false }
int	m_numTableRows { 0 }
QString	m_link {}
QString	m_sectionNumber {}
Static Protected Attributes inherited from Generator
static bool	s_redirectDocumentationToDevNull = false

Detailed Description

Generates documentation using external templates and a pre-built IR.

TemplateGenerator is designed to consume a complete IR (Intermediate Representation) that contains all resolved links, organized content sections, and file paths. The generator itself is "dumb": it only formats pre-resolved data according to template rules, without performing resolution, database lookups, or state modifications.

The generator follows QDoc's compile/link/render pipeline:

\list

{Build phase} (IRBuilder): Extract data from Node tree into IR. Handles all atom processing and Node interaction.
{Link phase} (HrefResolver, future): Resolve cross-module links.
{Render phase} (TemplateGenerator): Format IR into output. Implemented by {renderDocument()}, which knows nothing about Nodes. \endlist

The {generateXxx()} methods inherited from Generator are thin wrappers that call IRBuilder to build IR, then renderDocument() to format it. This separation ensures the render phase can be tested independently and that IR design is driven by actual rendering needs.

See also: IRBuilder, DocumentIR

Definition at line 16 of file templategenerator.h.

Constructor & Destructor Documentation

◆ TemplateGenerator()

TemplateGenerator::TemplateGenerator ( FileResolver & file_resolver )

explicit

Definition at line 60 of file templategenerator.cpp.

References Generator::Generator().

Here is the call graph for this function:

◆ ~TemplateGenerator()

TemplateGenerator::~TemplateGenerator ( )

overridedefault

Member Function Documentation

◆ fileExtension()

QString TemplateGenerator::fileExtension ( ) const

nodiscardoverrideprotectedvirtual

Implements Generator.

Definition at line 124 of file templategenerator.cpp.

◆ format()

QString TemplateGenerator::format ( ) const

overridevirtual

Returns the format identifier for this producer (e.g., "HTML", "DocBook", "template").

Used for format selection and matching. The identifier is case-sensitive and must match the value used in configuration files.

Implements Generator.

Definition at line 119 of file templategenerator.cpp.

◆ generateAtom()

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

overrideprotectedvirtual

Stub implementation - not yet IR-driven.

This method emits placeholder HTML comments and should not be relied upon for actual content rendering. Atom processing will be integrated with the IR system in future commits.

Reimplemented from Generator.

Definition at line 234 of file templategenerator.cpp.

References Generator::out().

Here is the call graph for this function:

◆ generateCollectionNode()

void TemplateGenerator::generateCollectionNode	(	CollectionNode *	cn,
		CodeMarker *	marker )

overrideprotectedvirtual

Reimplemented from Generator.

Definition at line 216 of file templategenerator.cpp.

References Generator::out().

Here is the call graph for this function:

◆ generateCppReferencePage()

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

overrideprotectedvirtual

Reimplemented from Generator.

Definition at line 142 of file templategenerator.cpp.

References Generator::out().

Here is the call graph for this function:

◆ generateDocs()

void TemplateGenerator::generateDocs ( )

overridevirtual

Traverses the database recursively to generate all the documentation.

Reimplemented from Generator.

Definition at line 129 of file templategenerator.cpp.

References Generator::generateDocs().

Here is the call graph for this function:

◆ generatePageNode()

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

overrideprotectedvirtual

Reimplemented from Generator.

Definition at line 164 of file templategenerator.cpp.

References IRBuilder::buildPageIR().

Here is the call graph for this function:

◆ generateQmlTypePage()

void TemplateGenerator::generateQmlTypePage	(	QmlTypeNode *	qcn,
		CodeMarker *	marker )

overrideprotectedvirtual

Reimplemented from Generator.

Definition at line 153 of file templategenerator.cpp.

References Generator::out().

Here is the call graph for this function:

◆ initializeGenerator()

void TemplateGenerator::initializeGenerator ( )

overridevirtual

No-op base implementation.

Subclasses may override to perform generator-specific initialization.

Reimplemented from Generator.

Definition at line 65 of file templategenerator.cpp.

References Generator::initializeGenerator().

Here is the call graph for this function:

◆ terminateGenerator()

void TemplateGenerator::terminateGenerator ( )

overridevirtual

Reimplemented from Generator.

Definition at line 114 of file templategenerator.cpp.

References Generator::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/templategenerator.h (11a5da505d0dc79d66f8b69a53e5b6e6ea1e5498)
qttools/src/qdoc/qdoc/src/qdoc/templategenerator.cpp (11a5da505d0dc79d66f8b69a53e5b6e6ea1e5498)

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ TemplateGenerator()

◆ ~TemplateGenerator()

Member Function Documentation

◆ fileExtension()

◆ format()

◆ generateAtom()

◆ generateCollectionNode()

◆ generateCppReferencePage()

◆ generateDocs()

◆ generatePageNode()

◆ generateQmlTypePage()

◆ initializeGenerator()

◆ terminateGenerator()