Wouldn't inline comments be more in line with "the code is the spec" philosophy? I would think it would be much less likely to get out of sync as the code changes. If someone modifies a function, changing the comment right above it seems more likely to happen than to go track down all the doc sites and make sure they're accurate.
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.
I agree. As I said, the wiki solution would be needed iff the Arc team does not want to do this. As an open tool provider myself I always invite those complaining about my doc to go ahead and contribute some. Great way to silence them. :) And maybe we can have the best of both worlds if we do the work collaboratively on a wiki which then periodically gets scraped into arc.arc so typical users are just looking at that. as an aside, if this happens I do think the wiki entries should also include the relevant code.
