Hyde: https://github.com/adobe/hyde generates C++ docs by parsing source code and generating separate docs for users to add to. Example output: https://stlab.cc/libraries/stlab2Fcopy_on_write.hpp/copy_on_write3CT3E/
They're absolutely right that inline docs can eventually become overwhelming when you're trying to read code.
Related Posts
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?
Go has an elegant approach to defining example functions, which are shown in docs as `main()` with the output: https://go.dev/blog/examples
There are docs resources like https://diataxis.fr/ that categorise documents based on format and intended audience.
They don't say where you should start, or what order you should write docs.
I'm currently thinking README > reference > tutorial > how-tos. Agree/disagree?