| HOME | CONSULTING | PUBLICATIONS | PROJECTS | CV (PDF) |
 |
cxxDocumentor An Extensible Grammar Parsing Code File Documentator |
Typical code documentation systems rely on comments included in C++ header files. By ignoring the inline comments programmers are naturally inclined to add, this technique fails to give any insight into the iner workings of code. I developed a documentation system that creates a grammar tree from C++ code files and produces a human readable outline from inline comments. I extended the base class to create a documentation system for Ygdrasil that automatically generates documentation for node messages and events.
 |
 |
| Project contributers are asked to place human readable comments within their code. | Each time a submitted file changes it is passed through a parser to generate a grammar tree. |
 |
 |
| Category and revision date are captured from the leading comments during the parsing process. Customizable template files use these tags to create individual class pages and an index and revisions page. | The comments meta tag produces an enumerated outline of the code structure. The resulting output forms a human readable description of the code functionality. All comments can be embelished with HTML tags. |
RELATED LINKS
The self-constructed documentation for cxxDocumentor.
Download location for the most recent version.
The Ygdrasil documentation site.
Documentation guidelines for user developed Ygdrasil nodes.
MORE DETAILS
 |
 |
The cxxDocument class can be extended to create customized documentation that leverages the grammar parsing. User developed nodes for the Ygdrasil system need their accepted messages and generated events documented. I created a subclass to look for patterns in the message method and construct human readable documentation using the class template messages meta tag. In the example above, the ygEnvironment fog message accepts either the argument "off" or one of four falloff types followed by five floats. The system is also able to do a limited evaluation of identfiers by constructing their value down a variable stack (below). The Ygdrasil documentation system uses this feature to automatically determine the names of variables returned by node events. For both messages and events, comments included immediately before their definition are included in the generated documentation.
|
 |
Grammar Parsing
The parsing of code files is rule based and does not use a true BNF representation of the C++ grammar. As a result, some language features, most notably the use of a dangling-else clause, are not handled. The grammar trees are constructed out of five principle types; functions, statements, conditionals, variables and comments. Because it only deconstructs the structures that it knows, the system can reconstruct compilable code from the grammar tree in most instances.