Overview of How CMinx Works

Parsing

In CMinx parsing of a source file is the role of the Antlr4 parsing runtime, generated from the modified CMake.g4 grammar file.

  1. As per the standard usage, the file contents are read into an Antlr4 FileStream, which is then passed to the generated CMake lexer.
  2. The lexer generates a token stream, which is then fed into the CMakeParser.
  3. The parser generates a tree of parse elements, called contexts, which are then walked over by the ParseTreeWalker.

This process is diagrammatically summarized in Fig. 1.

Aggregation

After the parser generates the parse tree, CMinx walks the tree and aggregates the various documentation.

  1. The walker calls the aggregator methods upon entering or exiting parse rules, such as entering a documented_command parse rule.
  2. The parse rule enterDocumented_command cleans the doccomment and extracts the documented command. For example, if a function definition is documented, enterDocumented_command will extract the function command.
  3. The aggregator then locates the subprocessor that corresponds to the extracted command, for example if the extracted command is function then the subprocessor would be process_function(). This subhandler is then executed with the parse context and cleaned docstring.
  4. The documentation aggregator subhandler generates NamedTuples representing the type of documentation generated, such as FunctionDocumentation, complete with all relevant information, and adds them to a documented list.
  5. From there, Documenter loops over the documentation list, generating equivalent RST via RSTWriter for each type of documentation.

This process is diagrammatically summarized in Fig. 2.