Generated documentation can be really really useful, but in my experience and opinion it needs to be a custom documentation generator. That's the approach I use

Generated documentation can be really really useful, but in my experience and opinion it needs to be a custom documentation generator. That's the approach I used with Autumn, where the generated HTML on the website is the same as in the app, so you can get a feel for it without trying the app out. The docs are concise, clear, good looking, organized in an easily navigable and understandable hierarchy, and with clickable references. I think what I came up with beats out commented code by far, although I did start to wonder if I should render the English portion of each node in my doc tree to be styled as a code-comment, just to draw more attention to the actual code signature itself. [1] https://sephware.com https://sephware.com