[FM Discuss] Documenting internals versus use (was: Beautiful Documentation with Sphinx)

[Andy Oram]

I'd like to take the discussion of Sphinx, etc. up a notch. Is it part of FM's mission to help developers document their code? That's basically an issue of internals. I suppose some of these javadoc-type of comments are also useful for API documentation, but I suspect that serious API documentation must be generated with a more comprehensive, high-level view of the API.

The idea of embedding comments in each function goes back to Knuth's WEB, which never went anywhere but seems to be reinvented with every new generation of programmers and every language.

Andy