Re: [swarm-hackers] Heatbug & Documentation

[Bill Northcott]

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 have some reservations about Git.  Yes it's cool, but it does seem  
to lead to endless branching and a situation where it is very  
difficult for users as opposed to hackers to find out what is going  
on.  I have wasted much time on other projects following dead Git  
branches.

I am not sure what the others think.

> 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.

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.
> 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

smime.p7s
Description: S/MIME cryptographic signature