Generate documentation from code
I think every software developer has thought about the best way to document the project.
Should you write it outside of the repository in a wiki?
Or should you put it in a doc folder within the repository?
Manual documentation
A README.md file is a simple and fast way to document e.g. the projects structure, steps to set it up, or the features it supports.
For more visual subjects, pictures or mermaid diagrams can be added.
Maybe more detailed documentation is placed outside of the repository in a wiki.
It often happened to me that I forgot to update the documentation after I changed the behavior or added a new feature. Then, I had to make another commit to fix that.
Automatic documentation
I assume that tools exist for most programming languages that can generate documentation, e.g., a website, based on the source code. For PHP, for example, there are phpDocumentor and Scramble, among others. These tools can be used in a CI/CD pipeline to automatically generate documentation after each code change.
Hybrid approach
In my opinion, the best solution for projects that want good documentation is a mix of documentation written by a developer or, nowadays, an AI assistant and documentation generated from the source code itself.
Example from my PHP interpreter
In my project QIQ, an PHP interpreter written in the Go, that approach is used.
The README.md is manually maintained by me.
Most of the documentation located in the doc/ folder is generated with the "doc-gen" tool in this project.
The generated documentation:
-
All supported constants
The category for the constants is given in a comment like// Const Category: Math.
For all constant definitions afterwards will be assigned to this category and the constant name is extracted from the code. -
All supported ini file directives
There is one file where all supported ini directives are defined in the source code.
The documentation reads this file and generates a list of them with the default value. -
All supported functions in the standard libray
This scans the directory where the standard library is implemented and gets the category from a comment like// Category: Math
The function names are extracted from the source code. -
All supported statements and expressions
The documentation generator can also generate a Markdown file from comments like// Supported expression: print expression: `print($v);`
This way I can just add this kind of comment in the parser where the expression is implemented.
Of all the features of the documentation generator, I am most proud of the dependency graph for the packages. This shows all Go packages of the QIQ project and how they are dependent on each other.
Changelog
- 2025-08-14: Renamed "GoPHP" to "QIQ"