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