On Mon, Nov 9, 2009 at 1:23 PM, Bill Northcott
<address@hidden> wrote:
On 09/11/2009, at 12:54 PM, Nima Talebi wrote:
As part of getting intimate with Swarm, I've decided to do the following:
1. Branch Heatbugs (probably into Git)
I am not sure what the others think.
I was not suggesting that everyone should switch over to git - only that I will create a separate branch to work on so I don't screw up anything in the official subversion codebase :)
And
here it is while I'm at it.
2. Rewrite relevant parts of http://www.swarm.org/swarmdocs-2.2/ inline in the code, using HeaderDoc - for example:
/*! @discussion Tutor
The first section of code says that a HeatbugModelSwarm is a kind of Swarm. HeatbugModelSwarm
inherits a lot of behavior from generic Swarm, but also adds new variables and methods.
*/
All such discussion will be labelled "Tutor"
Rewrite all existing comments as HeaderDoc comments, and regenerate a new document.
Once I get places, I'll send in some links, but meanwhile, if anyone has any suggestions which they'd like me to take on-board, I'm all ears :)
There is already a documentation system which generates the Objective-C and Java Reference Manuals. It is part of the same LISP code that generates the sources for the Java (and COM?) glue. IMO it works and there I can't see a compelling reason to change it.
Damn, I wish I'd read this earlier... I've already rewritten all of Heatbugs documentation in HeaderDoc format - well, at least we can treat it as a proof-of-concept.
It might be better to check that all the code includes the appropriate comment lines to generate the docs, and then build a 2.3 or 3.0 alpha reference. The Ruby principle is that documentation and tests are part of the code.
Do you have any documentation on the format of such comments, and example code that already uses it in the swarm codebase so I can have a look?
Note: I will not touch the Heatbugs source in subversion at all for now.
For what it is worth, I would rather see a Swarm 3 branch in SVN with an alpha release of runtime independent code, preferable without the nested functions.
Cheers
Bill
_______________________________________________
swarm-hackers mailing list
address@hidden
http://lists.nongnu.org/mailman/listinfo/swarm-hackers