Generator to produce valid but dummy C++ files from registered classes and functions. More...

#include <cpp_generator.h>

Public Member Functions
	CppGenerator (const string dir, ClassHierarchyProvider &chp, bool silent=false)
	Default constructor. More...

void	generate_cpp_files ()
	Generates C++ files for all registered classes and functions. More...

	~CppGenerator ()
	Destructor. More...

Private Member Functions

void	generate_class_group ()
	Generates C++ files for all classes in class groups. More...

void	generate_global_functions ()
	Generates C++ code for all global functions. More...


void	generate_class_docu ()
	Writes documentation for current class to current file. More...

void	generate_class_cpp ()
	Writes C++ code for current class to current file. More...


void	generate_class_constructors ()
	Writes documentation and declarations of constructors of current class. More...

void	generate_class_public_methods ()
	Generates documentation and declarations for all methods of current class. More...

void	generate_class_public_members ()
	Generates documentation and C++ signature for all public members of current class. More...


template<class TEntity >
void	write_brief_detail_docu (const TEntity &entity)
	Writes brief and detailed documentation for an entity. More...

template<class TFunction >
void	write_parameter_docu (const TFunction &function)
	Writes documentation for input parameters of given function. More...

template<class TFunction >
void	write_generic_function (const TFunction &function, bool constant=false)
	Writes documentation and declaration of given function. More...

void	write_group_definitions ()
	Writes some general docu on parent namespace. More...


template<class TFunction >
string	generate_parameter_list (const TFunction &func)
	Generates parameter list for the given function. More...

string	generate_return_value (const bridge::ExportedFunctionBase &method)
	Writes docu on return value and returns return value as string. More...


string	name_to_id (const string &str)
	Converts a group or class name to a portable ID. More...

string	parameter_to_string (const bridge::ParameterInfo &par, const int i) const
	Converts a value type to a string representation. More...

string	sanitize_parameter_name (const string &param) const
	Tunes parameter names to be valid C++ variable names. More...

string	sanitize_docstring (const string &docstring, bool is_brief=false)
	Detects empty tooltips and help and fills it with dummy content. More...

string	sanitize_docu (const string &param_docu) const
	Tunes parameter name to be rendered in docu. More...

vector< string >	split_group_hieararchy (const string group)
	Tokenizes given group name into its separate parts. More...

string	write_group_namespaces (vector< string > group_hierarchy, bool is_global_func=false)
	Converts group hierarchy into namespaces and writes them to file. More...

Private Attributes
bridge::IExportedClass *	m_curr_class
	Pointer to the currently processed class (if applicable) More...

fstream	m_curr_file
	Current file stream to write to. More...

bridge::ClassGroupDesc *	m_curr_group
	Pointer to the currently processed group (if applicable) More...

string	m_curr_group_name
	Name of current group as in ug4 itself (including namespaces) More...

bool	m_is_global
	Whether the currently processed function is global. More...

bool	m_is_plugin
	Whether the currently processed class or function is registered by a plugin. More...

string	m_output_dir

bool	m_silent

map< string, string >	m_written_classes
	Map for keeping track of already processed classes. More...

ClassHierarchyProvider &	mr_chp
	Reference to a helper for retrieving the class group of a class. More...

bridge::Registry &	mr_reg
	Reference to the registry (to save countless calls to ug::bridge::GetUGRegistry()) More...

Detailed Description

Generator to produce valid but dummy C++ files from registered classes and functions.

It requires the registry to be accessible by a call to ug::bridge::GetUGRegistry().

Constructor & Destructor Documentation

◆ CppGenerator()

ug::DocuGen::CppGenerator::CppGenerator	(	const string	dir,
		ClassHierarchyProvider &	chp,
		bool	silent = `false`
	)

Default constructor.

Parameters

dir	name and path of output directory for generated C++ files
silent	flag for suppressing verbose logging

◆ ~CppGenerator()

ug::DocuGen::CppGenerator::~CppGenerator ( )

Destructor.

if the file stream is still open, it closes it

References m_curr_file.

Member Function Documentation

◆ generate_class_constructors()

void ug::DocuGen::CppGenerator::generate_class_constructors ( )

private

Writes documentation and declarations of constructors of current class.

Only public constructors are written. In case there are no public constructors (i.e. the class is not instanciable), no constructors are written.

References ug::DocuGen::Doxygen::BRIEF, generate_parameter_list(), ug::bridge::IExportedClass::get_constructor(), ug::DocuGen::ClassHierarchyProvider::get_group(), ug::bridge::IExportedClass::is_instantiable(), m_curr_class, m_curr_file, mr_chp, ug::bridge::IExportedClass::name(), ug::bridge::IExportedClass::num_constructors(), UG_CATCH_THROW_FUNC, write_brief_detail_docu(), and write_parameter_docu().

Referenced by generate_class_cpp().

◆ generate_class_cpp()

void ug::DocuGen::CppGenerator::generate_class_cpp ( )

private

Writes C++ code for current class to current file.

This includes the C++ code and documentation for all members of the current class.

References ug::bridge::ClassNameNode::base_class(), ug::bridge::IExportedClass::class_name_node(), generate_class_constructors(), generate_class_public_members(), generate_class_public_methods(), ug::DocuGen::ClassHierarchyProvider::get_group(), m_curr_class, m_curr_file, mr_chp, ug::bridge::ClassNameNode::name(), ug::bridge::IExportedClass::name(), ug::bridge::ClassNameNode::num_base_classes(), UG_CATCH_THROW_FUNC, and UG_WARNING.

Referenced by generate_class_group(), and generate_cpp_files().

◆ generate_class_docu()

void ug::DocuGen::CppGenerator::generate_class_docu ( )

private

Writes documentation for current class to current file.

References ug::DocuGen::Doxygen::BRIEF, ug::DocuGen::Doxygen::CLASS, ug::DocuGen::ClassHierarchyProvider::get_group(), m_curr_class, m_curr_file, m_is_plugin, mr_chp, ug::bridge::IExportedClass::name(), ug::bridge::IExportedClass::tooltip(), UG_CATCH_THROW_FUNC, UG_WARNING, and ug::DocuGen::Doxygen::WARNING.

Referenced by generate_class_group(), and generate_cpp_files().

◆ generate_class_group()

void ug::DocuGen::CppGenerator::generate_class_group ( )

private

Generates C++ files for all classes in class groups.

This iterates over all registered class groups and generates one C++ file per group containing all classes in this group.

Usually a class group is a templated ug4 class and the classes in this group are specializations of this template depending on the build parameters of the linked libug4.

References generate_class_cpp(), generate_class_docu(), ug::bridge::ClassGroupDesc::get_default_class(), ug::DocuGen::ClassHierarchyProvider::get_group(), ug::bridge::IExportedClass::group(), m_curr_class, m_curr_file, m_curr_group, m_curr_group_name, m_is_plugin, m_output_dir, m_silent, m_written_classes, mr_chp, ug::bridge::ClassGroupDesc::name(), ug::bridge::IExportedClass::name(), name_to_id(), ug::DocuGen::Doxygen::NOTE, ug::DocuGen::Doxygen::SEE, split_group_hieararchy(), UG_CATCH_THROW_FUNC, UG_LOG, UG_WARNING, and write_group_namespaces().

Referenced by generate_cpp_files().

◆ generate_class_public_members()

void ug::DocuGen::CppGenerator::generate_class_public_members ( )

private

Generates documentation and C++ signature for all public members of current class.

Todo:: Not really implemented yet. Are there even any public members registered?

Referenced by generate_class_cpp().

◆ generate_class_public_methods()

void ug::DocuGen::CppGenerator::generate_class_public_methods ( )

private

Generates documentation and declarations for all methods of current class.

References ug::bridge::IExportedClass::get_const_method(), ug::bridge::IExportedClass::get_method(), m_curr_class, m_curr_file, ug::bridge::IExportedClass::num_const_methods(), ug::bridge::IExportedClass::num_methods(), UG_CATCH_THROW_FUNC, and write_generic_function().

Referenced by generate_class_cpp().

◆ generate_cpp_files()

void ug::DocuGen::CppGenerator::generate_cpp_files ( )

◆ generate_global_functions()

void ug::DocuGen::CppGenerator::generate_global_functions ( )

private

Generates C++ code for all global functions.

This iterates over all global functions and writes their documentation and declaration to the file global_functions.cpp.

References ug::bridge::Registry::get_function(), ug::bridge::ExportedFunction::group(), m_curr_file, m_is_global, m_is_plugin, m_output_dir, mr_reg, ug::bridge::Registry::num_functions(), split_group_hieararchy(), UG_CATCH_THROW_FUNC, UG_LOG, write_generic_function(), and write_group_namespaces().

Referenced by generate_cpp_files().

◆ generate_parameter_list()

template<class TFunction >

string ug::DocuGen::CppGenerator::generate_parameter_list ( const TFunction & func )

private

Generates parameter list for the given function.

Generates the parameter list as in function declerations for the given registered method. The enclosing brakets ('(' and ')') are also written.

Template Parameters

TFunction

a function type usually either derived from ug::bridge::ExportedFunctionBase or ug::bridge::ExportedConstructor providing at least the members

int num_parameter()
ParameterInfo params_in()
string parameter_name( size_t i )

Parameters

func	method object to be used

Returns: parameter list

References parameter_to_string(), sanitize_parameter_name(), and UG_CATCH_THROW_FUNC.

Referenced by generate_class_constructors(), and write_generic_function().

◆ generate_return_value()

string ug::DocuGen::CppGenerator::generate_return_value ( const bridge::ExportedFunctionBase & method )

private

Writes docu on return value and returns return value as string.

Documentation on the return value of the given function method is written to m_curr_file.

A single return value is converted into a valid C++ string by utilizing ug::bridge::ParameterToString(). If func has no return value, void is displayed and returned.

Parameters

method the method to generated the return value for

Returns: the return value of func as a string

Todo:: Implement handling of multiple return values. Currently they are displayed as '()'. This might be superfluous if there are no methods with more than one return value registered.

References m_curr_file, parameter_to_string(), ug::bridge::ExportedFunctionBase::params_out(), ug::bridge::ExportedFunctionBase::return_info(), ug::DocuGen::Doxygen::RETURNS, sanitize_docu(), ug::bridge::ParameterInfo::size(), UG_CATCH_THROW_FUNC, and UG_WARNING.

Referenced by write_generic_function().

◆ name_to_id()

string ug::DocuGen::CppGenerator::name_to_id ( const string & str )

inlineprivate

Converts a group or class name to a portable ID.

It

deletes all whitespaces
replaces all occurrences of '/' by '_'
Parameters

str initial name to convert

Returns
converted name

Referenced by generate_class_group(), generate_cpp_files(), and split_group_hieararchy().

◆ parameter_to_string()

string ug::DocuGen::CppGenerator::parameter_to_string	(	const bridge::ParameterInfo &	par,
		const int	i
	)		const

private

Converts a value type to a string representation.

ug4's internal classes are correctly substituted as well as other registered classes and types.

Parameters

[in]	par	parameter stack
[in]	i	index of the parameter from the parameter stack

Returns: string representation of the i'th parameter type

References ug::bridge::ParameterInfo::class_name(), ug::DocuGen::ClassHierarchyProvider::get_group(), ug::bridge::ParameterInfo::is_vector(), mr_chp, ug::bridge::ParameterInfo::type(), ug::Variant::VT_BOOL, ug::Variant::VT_CONST_POINTER, ug::Variant::VT_CONST_SMART_POINTER, ug::Variant::VT_CSTRING, ug::Variant::VT_DOUBLE, ug::Variant::VT_FLOAT, ug::Variant::VT_INT, ug::Variant::VT_INVALID, ug::Variant::VT_POINTER, ug::Variant::VT_SIZE_T, ug::Variant::VT_SMART_POINTER, and ug::Variant::VT_STDSTRING.

Referenced by generate_parameter_list(), and generate_return_value().

◆ sanitize_docstring()

string ug::DocuGen::CppGenerator::sanitize_docstring	(	const string &	docstring,
		bool	is_brief = `false`
	)

inlineprivate

Detects empty tooltips and help and fills it with dummy content.

For an empty tooltip (e.g. a brief docu) the string "no brief documentation" is used; for an empty help (e.g. a detailed docu) the string "no documentation" is used

Parameters

[in]	docstring	either a tooltip or help text
[in]	is_brief	indicator whether the `docstring` is a tooltip

Returns: sanitized docstring

Referenced by write_brief_detail_docu().

◆ sanitize_docu()

string ug::DocuGen::CppGenerator::sanitize_docu ( const string & param_docu ) const

inlineprivate

Tunes parameter name to be rendered in docu.

In case the given parameter is empty, it is rendered as undocumented. Otherwise it is returned as it.

Parameters

param_docu parameter to be preprocessed for docstring.

Returns: preprocessed parameter name

Referenced by generate_return_value().

◆ sanitize_parameter_name()

string ug::DocuGen::CppGenerator::sanitize_parameter_name ( const string & param ) const

inlineprivate

Tunes parameter names to be valid C++ variable names.

In case the given parameter name is empty, it is rendered as unnamed. Otherwise it trims leading and trailing whitespaces and replaces the remaining whitespaces by underscores.

Parameters

param parameter name to be preprocessed

Returns: sanitized parameter name

See also: sanitize_docu

Referenced by generate_parameter_list(), and write_parameter_docu().

◆ split_group_hieararchy()

vector< string > ug::DocuGen::CppGenerator::split_group_hieararchy ( const string group )

private

Tokenizes given group name into its separate parts.

Splits the given group name at the characters '_' and '/'.

Parameters

group group name to be tokenized

Returns: vector of strings of tokens

References ug::find(), m_is_plugin, and name_to_id().

Referenced by generate_class_group(), generate_cpp_files(), and generate_global_functions().

◆ write_brief_detail_docu()

template<class TEntity >

void ug::DocuGen::CppGenerator::write_brief_detail_docu ( const TEntity & entity )

private

Writes brief and detailed documentation for an entity.

Writes the brief and detailed documentation for the given entity to the current file.

Template Parameters

TEntity

Either a registered class or function, which provides the members

string tooltip()
string help()

Parameters

entity Class or function to be documented

References ug::DocuGen::Doxygen::BRIEF, ug::DocuGen::Doxygen::DETAILS, m_curr_file, and sanitize_docstring().

Referenced by generate_class_constructors(), and write_generic_function().

◆ write_generic_function()

template<class TFunction >

void ug::DocuGen::CppGenerator::write_generic_function	(	const TFunction &	function,
		bool	constant = `false`
	)

private

Writes documentation and declaration of given function.

Writes the full documentation and method signature of the given function to the current file.

Template Parameters

TFunction

a function type usually derived from ug::bridge::ExportedFunctionBase providing at least the members

string name()
int num_parameter()
ParameterInfo params_in()
string parameter_name( size_t i )

Parameters

function	function to be written
constant	whether the function is const or not

References generate_parameter_list(), generate_return_value(), m_curr_file, m_curr_group_name, m_is_global, m_is_plugin, UG_CATCH_THROW_FUNC, ug::DocuGen::Doxygen::WARNING, write_brief_detail_docu(), and write_parameter_docu().

Referenced by generate_class_public_methods(), and generate_global_functions().

◆ write_group_definitions()

void ug::DocuGen::CppGenerator::write_group_definitions ( )

private

Writes some general docu on parent namespace.

also warning for the plugin namespace

References ug::DocuGen::Doxygen::BRIEF, m_curr_file, m_output_dir, UG_CATCH_THROW_FUNC, and ug::DocuGen::Doxygen::WARNING.

Referenced by generate_cpp_files().

◆ write_group_namespaces()

string ug::DocuGen::CppGenerator::write_group_namespaces	(	vector< string >	group_hierarchy,
		bool	is_global_func = `false`
	)

private

Converts group hierarchy into namespaces and writes them to file.

Creates a namespace for each element of the group vector while empty group names are ignored and the group name ug4 is replaced by ug4bridge .

Parameters

[in] group_hierarchy vector of groups as returned by split_group_hieararchy(group)

Returns: string with the closing namespace brackets

References m_curr_file.

Referenced by generate_class_group(), generate_cpp_files(), and generate_global_functions().

◆ write_parameter_docu()

template<class TFunction >

void ug::DocuGen::CppGenerator::write_parameter_docu ( const TFunction & function )

private

Writes documentation for input parameters of given function.

For each input parameter of the given function the documentation is written to the current file

Template Parameters

TFunction

a function type usually either derived from ug::bridge::ExportedFunctionBase or ug::bridge::ExportedConstructor providing at least the members

int num_parameter()
string parameter_name( size_t i )

Parameters

function function to be documented

References m_curr_file, ug::DocuGen::Doxygen::PARAM_IN, and sanitize_parameter_name().

Referenced by generate_class_constructors(), and write_generic_function().

Member Data Documentation

◆ m_curr_class

bridge::IExportedClass* ug::DocuGen::CppGenerator::m_curr_class

private

Pointer to the currently processed class (if applicable)

Referenced by generate_class_constructors(), generate_class_cpp(), generate_class_docu(), generate_class_group(), generate_class_public_methods(), and generate_cpp_files().

◆ m_curr_file

fstream ug::DocuGen::CppGenerator::m_curr_file

private

Current file stream to write to.

Referenced by generate_class_constructors(), generate_class_cpp(), generate_class_docu(), generate_class_group(), generate_class_public_methods(), generate_cpp_files(), generate_global_functions(), generate_return_value(), write_brief_detail_docu(), write_generic_function(), write_group_definitions(), write_group_namespaces(), write_parameter_docu(), and ~CppGenerator().

◆ m_curr_group

bridge::ClassGroupDesc* ug::DocuGen::CppGenerator::m_curr_group

private

Pointer to the currently processed group (if applicable)

Referenced by generate_class_group(), and generate_cpp_files().

◆ m_curr_group_name

string ug::DocuGen::CppGenerator::m_curr_group_name

private

Name of current group as in ug4 itself (including namespaces)

Referenced by generate_class_group(), generate_cpp_files(), and write_generic_function().

◆ m_is_global

bool ug::DocuGen::CppGenerator::m_is_global

private

Whether the currently processed function is global.

Referenced by generate_global_functions(), and write_generic_function().

◆ m_is_plugin

bool ug::DocuGen::CppGenerator::m_is_plugin

private

Whether the currently processed class or function is registered by a plugin.

Referenced by generate_class_docu(), generate_class_group(), generate_global_functions(), split_group_hieararchy(), and write_generic_function().

◆ m_output_dir

string ug::DocuGen::CppGenerator::m_output_dir

private

Referenced by generate_class_group(), generate_cpp_files(), generate_global_functions(), and write_group_definitions().

◆ m_silent

bool ug::DocuGen::CppGenerator::m_silent

private

Referenced by generate_class_group(), and generate_cpp_files().

◆ m_written_classes

map<string, string> ug::DocuGen::CppGenerator::m_written_classes

private

Map for keeping track of already processed classes.

Key is the class name, which maps to the file name this class has been written to.

Referenced by generate_class_group(), and generate_cpp_files().

◆ mr_chp

ClassHierarchyProvider& ug::DocuGen::CppGenerator::mr_chp

private

Reference to a helper for retrieving the class group of a class.

Referenced by generate_class_constructors(), generate_class_cpp(), generate_class_docu(), generate_class_group(), generate_cpp_files(), and parameter_to_string().

◆ mr_reg

bridge::Registry& ug::DocuGen::CppGenerator::mr_reg

private

Reference to the registry (to save countless calls to ug::bridge::GetUGRegistry())

Referenced by generate_cpp_files(), and generate_global_functions().

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

/home/runner/work/docs/docs/ug4/plugins/DocuGen/src/cpp_generator.h
/home/runner/work/docs/docs/ug4/plugins/DocuGen/src/cpp_generator.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ CppGenerator()

◆ ~CppGenerator()

Member Function Documentation

◆ generate_class_constructors()

◆ generate_class_cpp()

◆ generate_class_docu()

◆ generate_class_group()

◆ generate_class_public_members()

◆ generate_class_public_methods()

◆ generate_cpp_files()

◆ generate_global_functions()

◆ generate_parameter_list()

◆ generate_return_value()

◆ name_to_id()

◆ parameter_to_string()

◆ sanitize_docstring()

◆ sanitize_docu()

◆ sanitize_parameter_name()

◆ split_group_hieararchy()

◆ write_brief_detail_docu()

◆ write_generic_function()

◆ write_group_definitions()

◆ write_group_namespaces()

◆ write_parameter_docu()

Member Data Documentation

◆ m_curr_class

◆ m_curr_file

◆ m_curr_group

◆ m_curr_group_name

◆ m_is_global

◆ m_is_plugin

◆ m_output_dir

◆ m_silent

◆ m_written_classes

◆ mr_chp

◆ mr_reg