I prefer inline comments with explanation and examples. If you want a somewhat decent example, think of (dare I say it) Javadoc comments and Rdoc comments. Someone just needs to write something (in arc of course) to parse .arc files and build up html docs, then you can have them on a website and in the code, but the code is the authority.
If pg & co. will add the comments and/or accept patches from users with comments, then yes, this would be the best method for function reference documentation, especially given Arc's present volatility.
