From the tutorial: "The definitions in arc.arc are also an experiment in another way.
They are the language spec." I actually love that idea, but with Arc there is a problem: many of the function names are inscrutable. So as I am studying the spec (the code) I am handicapped by not even knowing what the function is supposed to be doing! And the body of these functions of course include calls to other inscrutable (sometimes) names which I will not read fluently until I have programmed Arc for a few weeks. ie this is like pulling teeth. I have a great package I want to be porting to Arc, I don't want to be decrypting the Rosetta Stone! :) I propose that arc.arc be commented with expansions for all abbreviations, possibly even a whole sentence saying what the thing does. My super fantasy includes small examples with their outputs. If the Arc team hates this idea, maybe an Arc Wiki is the way to go?
I think a comment for each function is perfectly reasonable. Hopefully the lack of comments is more due to a lack of time to add them than a philosophical bent against them.
"... My super fantasy includes small examples with their outputs. If the Arc team hates this idea, maybe an Arc Wiki is the way to go? ..."
Damn I missed this thread. The examples are exactly the way to go. My idea was something along the lines of a snippets collection by user, title plus code and unique url. [0] This means the good code rises to the top, is stored at arclanguage for all to see and read. Sorted by hacker. At some time in the future it could also be run server-side - something pg has hinted in the past.
"... maybe an Arc Wiki is the way to go? ..."
But this idea is more focussed on describing the code. Is there anyway a code document generator could be written extracting
- filename
- function name
- description
to auto generate the documentation much like Python? [1] This one thing Guido got right - documentation: A tutorial (already exists) and the module index (does not). [2] By having a PyDoc equivalent running over the latest version of Arc you can have a arclanguage.org/doc url with a module index plus the tutorial.
This is how python became so damn useful. You could find how to solve a problem reading both the tutorial, then check the module index to read the details. Sure beats having to do a wiki which arclanguage pretty much covers sans the markup.
Surely more documentation is forthcoming from pg when he has time, and some other folks will likely write up docs until then. I started on "redocumenting" the arc spec file, but I don't have oodles of free time myself... A wiki-esque page would be nice.
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.
