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. |
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.
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. |
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'