This namespace holds QDoc-internal utility methods. More...

Enumerations
enum class	ExampleFileKind { File , Image }

Functions
void	startDebugging (const QString &message)
void	stopDebugging (const QString &message)
bool	debugging ()
const INode *	nodeForString (const QString &string)
	Converts a string representation of a pointer address to an INode pointer.
QString	stringForNode (const INode *node)
	Converts an INode pointer address to its string representation.
QString	uniqueIdentifier (const Location &loc, const QString &prefix)
	Returns a unique identifier based on location loc, with a given prefix.
QStringList	getInternalIncludePaths (const QString &compiler)
bool	isGeneratedFile (const QString &path)
QStringList	pathAndFragment (const QString &linkText)
	Returns a string list containing the path and fragment components of the given linkText.
QString	linkForExampleFile (const QString &path, const QString &project, const QString &fileExt)
	Constructs an href link from an example file name.
QString	exampleFileTitle (const QString &fileName, ExampleFileKind kind)
	Constructs a title for a file or image page in an example.
QString	exampleFileTitle (const QStringList &files, const QStringList &images, const QString &fileName)
	Constructs a title for a file or image page in an example.
QString	computeFileBase (const Node node, const QString &project, const std::function< QString(const Node )> &prefixFn, const std::function< QString(const Node *)> &suffixFn)
static void	setDebugEnabled (bool value)
static bool	runProcess (const QString &program, const QStringList &arguments, QByteArray stdOutIn, QByteArray stdErrIn)
static QByteArray	frameworkSuffix ()

Detailed Description

This namespace holds QDoc-internal utility methods.

Enumeration Type Documentation

◆ ExampleFileKind

enum class Utilities::ExampleFileKind

strong

Enumerator
File
Image

Definition at line 35 of file utilities.h.

Function Documentation

◆ computeFileBase()

QString Utilities::computeFileBase	(	const Node *	node,
		const QString &	project,
		const std::function< QString(const Node *)> &	prefixFn,
		const std::function< QString(const Node *)> &	suffixFn )

Computes the base filename for a documentation page node.

This is the shared implementation used by both Generator::fileBase() and TemplateGenerator::fileBase(). The caller is responsible for navigating to the page/collection node and for caching the result; this function performs only the pure filename computation.

The node must already be a page node or collection node. The project string is used for example page prefixes. The prefixFn and suffixFn callbacks supply the caller-specific output prefix and suffix (which differ between Generator and TemplateGenerator due to their different configuration mechanisms).

Note: This function lives in its own compilation unit (filebase.cpp) rather than utilities.cpp because it depends on Node, Config, and other heavyweight QDoc types. Keeping utilities.cpp free of these dependencies allows lightweight test targets to compile it without pulling in the full QDoc infrastructure.

Definition at line 40 of file filebase.cpp.

References Node< _Tp >::createContext(), Node< _Tp >::isCollectionNode(), Node< _Tp >::isExample(), InclusionFilter::isIncluded(), Node< _Tp >::isModule(), Node< _Tp >::isNamespace(), Node< _Tp >::isProxyNode(), Node< _Tp >::isQmlBasicType(), Node< _Tp >::isQmlModule(), Node< _Tp >::isQmlType(), Node< _Tp >::isTextPageNode(), Node< _Tp >::logicalModule(), and Node< _Tp >::parent().

Here is the call graph for this function:

◆ debugging()

bool Utilities::debugging ( )

Definition at line 39 of file utilities.cpp.

Referenced by processQdocconfFile().

Here is the caller graph for this function:

◆ exampleFileTitle() [1/2]

QString Utilities::exampleFileTitle	(	const QString &	fileName,
		ExampleFileKind	kind )

nodiscard

Constructs a title for a file or image page in an example.

Returns the base name of fileName with the appropriate suffix based on kind: " Example File" for ExampleFileKind::File, " Image File" for ExampleFileKind::Image.

Use this overload when you already know whether the file is an example file or image (e.g., when iterating separate file/image lists).

Definition at line 248 of file utilities.cpp.

◆ exampleFileTitle() [2/2]

QString Utilities::exampleFileTitle	(	const QStringList &	files,
		const QStringList &	images,
		const QString &	fileName )

nodiscard

Constructs a title for a file or image page in an example.

If fileName is found in files, returns the base name with " Example File" suffix. If found in images, returns the base name with " Image File" suffix. If not found in either list, returns an empty string.

Matching uses exact string equality, not basename comparison.

Note: This overload performs O(n) membership checks. When iterating known file or image lists, prefer the overload taking ExampleFileKind.

Definition at line 275 of file utilities.cpp.

◆ frameworkSuffix()

QByteArray Utilities::frameworkSuffix ( )

static

Definition at line 128 of file utilities.cpp.

◆ getInternalIncludePaths()

QStringList Utilities::getInternalIncludePaths ( const QString & compiler )

Determine the compiler's internal include paths from the output of

\badcode [clang++|g++] -E -x c++ - -v </dev/null

Output looks like:

\badcode #include <...> search starts here: /usr/local/include /System/Library/Frameworks (framework directory) End of search list.

Definition at line 149 of file utilities.cpp.

◆ isGeneratedFile()

bool Utilities::isGeneratedFile ( const QString & path )

Definition at line 182 of file utilities.cpp.

◆ linkForExampleFile()

QString Utilities::linkForExampleFile	(	const QString &	path,
		const QString &	project,
		const QString &	fileExt )

nodiscard

Constructs an href link from an example file name.

The path is the path to the example file. The project is the module name (used as prefix). The fileExt is the file extension for the generated link.

Definition at line 232 of file utilities.cpp.

◆ nodeForString()

const INode * Utilities::nodeForString ( const QString & string )

Converts a string representation of a pointer address to an INode pointer.

This function takes a string, assumed to contain the numerical representation of an INode pointer's address (as generated by stringForNode()), and casts it back to an INode pointer.

See also: stringForNode()

Definition at line 53 of file utilities.cpp.

◆ pathAndFragment()

QStringList Utilities::pathAndFragment ( const QString & linkText )

Returns a string list containing the path and fragment components of the given linkText.

Fragments begin with a "#" character, following HTML conventions.

Links with only a path or only a fragment will result in lists of one element. A link with both path and fragment will result in a list of two elements. Additional fragments are discarded.

Escaped "#" characters ("\\#") are interpreted differently to regular "#" characters. These can be used to represent "#" characters in titles, but not in fragments.

Definition at line 203 of file utilities.cpp.

◆ runProcess()

bool Utilities::runProcess	(	const QString &	program,
		const QStringList &	arguments,
		QByteArray *	stdOutIn,
		QByteArray *	stdErrIn )

static

Definition at line 87 of file utilities.cpp.

◆ setDebugEnabled()

void Utilities::setDebugEnabled ( bool value )

inlinestatic

Definition at line 21 of file utilities.cpp.

Referenced by startDebugging(), and stopDebugging().

Here is the caller graph for this function:

◆ startDebugging()

void Utilities::startDebugging ( const QString & message )

Definition at line 27 of file utilities.cpp.

References setDebugEnabled().

Here is the call graph for this function:

◆ stopDebugging()

void Utilities::stopDebugging ( const QString & message )

Definition at line 33 of file utilities.cpp.

References setDebugEnabled().

Here is the call graph for this function:

◆ stringForNode()

QString Utilities::stringForNode ( const INode * node )

Converts an INode pointer address to its string representation.

This function takes a node pointer and returns a string that contains the numerical value of its memory address. This is used for serialization or passing node references where a direct pointer cannot be used.

Note: The returned string is only valid within the same process. It does {not} persist across runs.

Definition at line 67 of file utilities.cpp.

◆ uniqueIdentifier()

QString Utilities::uniqueIdentifier	(	const Location &	loc,
		const QString &	prefix )

Returns a unique identifier based on location loc, with a given prefix.

Definition at line 76 of file utilities.cpp.

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ExampleFileKind

Function Documentation

◆ computeFileBase()

◆ debugging()

◆ exampleFileTitle() [1/2]

◆ exampleFileTitle() [2/2]

◆ frameworkSuffix()

◆ getInternalIncludePaths()

◆ isGeneratedFile()

◆ linkForExampleFile()

◆ nodeForString()

◆ pathAndFragment()

◆ runProcess()

◆ setDebugEnabled()

◆ startDebugging()

◆ stopDebugging()

◆ stringForNode()

◆ uniqueIdentifier()