# docgen.h ## Overview
docgen parses files in the source code using a simplistic parser and extracts documentation into a [Markdeep](https://casual-effects.com/markdeep/) document that can be viewed in a web browser. You can generate documentation for a file or folder and open it in the web browser with: ~~~sh docgen -e PATH ~~~ When you are generating documentation for a folder, `docgen` finds .h, .inl and .md files in the folder and generates documentation for them. If you pass a single file, you can also generate documentation for .c files. See `docgen --help` for more information on how to run docgen. To write documentation for use with docgen, simply put a documentation comment in front of the thing you want to document. Example: ~~~c // A struct with some information. struct my_struct { int a; }; ~~~ docgen works by first splitting the file into "blocks" separated by blank lines. You can have multiple declarations in a single block, but be aware that they will all be shown under the same heading in the documentation: ~~~c // Multiple stuff. #define A 7 #define B 14 ~~~ To avoid confusing docgen, avoid mixing different kinds of declarations in the same block: ~~~c // Multiple stuff. #define A 7 enum {B = 14}; ~~~ The first comment without a code block in a source file is used as the *Overview* documentation for the whole source file. Any subsequent free standing comments are used as section dividers in the *Index*: ~~~c // This file deals with X and Y. // X stuff // Does X. void x(); // Y stuff // Does Y. void y(); ~~~ `#include` blocks and `#ifdef` blocks are automatically excluded from the documentation. To force exclusion of other blocks, put `tm_docgen ignore` in the block's comment. You can also turn off documentation for all the code that follows with `tm_docgen off` and turn it back on again with `tm_docgen on`. Note that docgen is heavily dependent on the conventions used in The Machinery codebase, both concerning the formatting and the layout of the APIs. If you deviate from those conventions, documentation may not be correctly generated. References can be inserted in the source code using double brackets: [[tm_allocator_api->create_child()]]. * A fully specified reference (`tm_allocator_api->create_child()`) can be used anywhere. * In the file where the reference is defined, the shortened form `create_child` can be used.