CxxDoc template language

CxxDoc uses series of directories to generate documentation:

• (install dir)/Tools/CxxDoc/Class/* are the scripts used to generate HTML for the Class dir of the documentation.
• (install dir)/Tools/CxxDoc/DocNode/* are the scripts used to generate HTML for the Tree dir of the documentation.
• (install dir)/Tools/AutoDoc/EHT/* is the set of extra documention pages to be place in the documentation tree. EHT stands for Embedded Hyper Text, as the pages are wrapped with headers and footers generated from the templates. These files are copied here by QMake from files listed in the EHT tag.

CxxDoc template commands

CxxDoc works by parsing all the headers from a project, generating a 'parse tree`, then using a stack based approach to traverse the tree. Commands such as 'forall' (see below) push a new context onto the stack.

CxxDoc uses the basic text template system, these commands can be found in Ravl.OS.Text_Processing.Templates, and adds the following commands to deal with the parse tree.

$(forall:a:b)	For all child objects in the current scope of type 'a' push it on the stack, expand 'b', pop it off. Where 'a' may be one of class, namespace, docnode, datatype, method, typedef, variable, inherit, derived and enum. See table below for more information on these objects. Setting localScopeOnly to '1' can be used to limit the iteration to the local scope only
$(ifany:a:b)	If there is any child objects of type 'a' in the current scope expand 'b'.
$(MakeFilename:a)	Make a filename for the current object, '%' is
$(GotoInherit:a)	If the current object is of type 'inherit', push inherited object onto the stack expand 'a' and pop it off.
$(HtmlMethodName:)	Generate a method name with all components marked up with html links.
$(HtmlTypeName:)	Generate a type name with all components marked up with html links.
$(AutoLink:a)	Expand 'a' and search it for type names, if found create html links to them. autoLinkContext can be used to explicitly set the scope used for the search.
$(Exec:a:b)	Expand to the standard output of program 'a' when 'b' is into its standard input. This will terminate the program if it does not terminate in 30 seconds and append an error message to the generated text.
$(ForDir:a)	Not yet implemented. Indended to go through all the files in a directory and process them.
$(MakeDocNode:a)	Add current page to the documentation tree using 'a' as its docentry.

Object types

At the begining of each template file there are two commands. The first, 'FileObject', specifies the which object the template documents, one template file will be generated for each instance of this type of object found in the parse tree. The second, 'FilePattern' specifies the form the filename should take. For example the following line at the begining of a template file will generate a page for every class, with a file name of Class/(object name).html.

$(FileObject:class)$(FilePattern:Class/%.html)

Following is a list of object types that can be use as file objects or in 'ForAll' and 'IfAny' commands.

Object type	Usage	function.
class	forall,FileObject	classes.
namespace	forall,FileObject	namespaces
datatype	forall,FileObject	datatypes
method	forall,FileObject	class methods
function	forall,FileObject	global functions.
typedef	forall,FileObject	typedefs
variable	forall,FileObject	variables
inherit	forall,FileObject	inheritance, from class scopes only.
derived	forall,FileObject	derived classes, from class scopes only.
enum	forall,FileObject	enumerated types.
docnode	forall,FileObject	Documentation nodes.
none	FileObject	Ignore template file.
one	FileObject	Create one file using the name from the 'FilePattern'.
file:(dir)	FileObject	For each file in a directory.

Variables

Nearly all variables set in C++ classes with '//! xyz="..."' can be accessed in the corresponding scope with $(xyz). There are some special variables, these are as follows:

• ObjectName - Name of the current object.
• Name - Name of the current object.
• FullName - Full name of object.
• ClassName - Name of object removing any template qualifiers.
• InheritFrom - Name of class which is inherits from in, set in an 'inherit' object only.
• ParentScope - Name of the parent scope.
• typedef_type - Actual type in a typedef. (Not its alias)
• brief - Text from a brief part of a comment.
• detail - Text from a detail part of a comment.
• buildtime - Current time.
• NodeType - Type of current node.
• href - generate a name suitable for use in local link.
• storageType - Type of structure, 'class' 'union' 'struct' or 'namespace'
• userlevel - If not set the system automaticly sets this to 'Default'.
• PathName - Full path to object in scope.
• filename - File which the object comes from this searches up the parse tree for an object with this variable set.
• docNodeType - Type of the current doc node, generaly either a 'class' or a 'method', but could be any of object types mentioned earlier.
• autoLinkContext - Used to set the context of the name search used in auto linking.
• autoLink - Set the type of auto linking to be used for a piece of text. It can be 'on', 'off' or 'marked'. If marked is selected only text between '[' and ']' is checked for a linking.
• localScopeOnly - When set to '1' it limits $(forall:a:b) to the local scope, it ignores any inheritance relations.
• refPattern - This holds the pattern of the filename used to generate html links. e.g. '../Basic/Class/%.html'