Sharing is caring, thanks for your code, but....

[3298]

All this talk about mixing source code and docs reminds me of Doxygen, which is a popular tool for just that. HPGCC3 uses it, to name just one HP-related example. (Here's the extracted documentation.)
A very convenient feature of the Doxygen system is that the documentation is stuffed into the programming language's comments, which turns source code extraction a no-op. (Sure, you could strip out the comments, but what's the point when the compiler will ignore them anyway?) Being mostly text-based, the documentation often doesn't have to be extracted either to be helpful. Some lazy programmers (including myself) simply read the comments containing the documentation instead. The plain-text editors used for editing the source code usually don't help in presenting the documentation in a nice way (beyond some basic syntax highlighting for Doxygen's keywords), so you lose the markup, any embedded images will have to be found and opened by the user, and all references need to be manually searched for, but most of the time the pure text in a comment preceding a function is enough to understand the function's code. If it isn't, then chances are that the full documentation rendered into HTML pages won't help either, in which case you better yell at the original author to provide proper docs, or bite the bullet and just try to follow the code.

In the end, everything just boils down to writing useful comments into the source. If you want to be nice, you format them for Doxygen so the weirdos who want some pretty docs can extract them, but I'd call even that optional. Putting the documentation as close as possible to the code it documents is the more important thing, because it keeps the programmer and later maintainers from getting distracted and/or annoyed at the constant switching between code and doc while writing / reading these. Some additional higher-level introduction or explanation of concepts for more complex pieces of code can go anywhere really, as long as it's easy to find for those who need it (e.g. at the top of the main source file relevant to the topic - or for the smaller snippets that started this discussion: before or after the entire code).

For our beloved HP calculators, I'd rate onboard doc-extracting programs as unnecessary. You can't easily switch between docs and code, so having the docs embedded into the code as comments is the most useful way. When there is another device nearby that can display separate documentation (e.g. a PC), that becomes less true, but since the documented code probably has to pass through that device to get into the calculator, it would be more fitting to use existing doc extraction tools on that device instead, if at all. So keep documenting your RPL with embedded raw text comments and/or forum posts, and all is well.