Arc Forumnew | comments | leaders | submitlogin
8 points by lojic 5901 days ago | link | parent

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.


4 points by Xichekolas 5901 days ago | link

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.

(In fact, this gives me something to do tonight.)

-----

1 point by tjr 5901 days ago | link

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.

-----

3 points by kennytilton 5900 days ago | link

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.

-----

1 point by Gotttzsche 5900 days ago | link

Maybe we should do a temporary wiki and just paste arc.arc in it so everyone can add comments in a centralized way.

Maybe get one at wikia? (they are for free, right?)

edit: nevermind, there's already git.nex-3.com :)

-----