I'm coming round to the view that optimum documentation is one web page per function.
This gives you space for prose, examples, related functions, version history and even user comments!
It's not the norm though, and requires substantial content writing.
Related Posts
I'm coming round to the view that a main function shouldn't take arguments.
For example, in Rust you have to call std::env::args() to get CLI arguments.
This makes Hello World less verbose, and gives you more flexibility in setting up CLI argument parsers.
ASTs typically discard comments, and that's usually what you want.
The only time (AFAICS) that preserving comments is useful is for writing a code formatter.
Could you write a formatter in terms of a list of lexemes? A CST is a non-trivial bit of code for one use case.
I've been writing docs for different programming language operators (+, *, == and so on). Each one gets a separate web page.
I've suddenly realised that / is much harder! docs/+ and docs/== is fine, but docs// just doesn't work as a URL in a static site.
Any ideas?