Making the move...

[Geoff Canyon]

On Mar 17, 2006, at 1:20 PM, Mark Wieder wrote:

> ...sure there is. You have to roll your own, but it's not that much
> transcript code. My libraries generate their own documentation through
> a javadoc-like mechanism. Check out, for example, my ArchiveSearch
> plugin on revonline and open the libDispatcher library. Click on the
> API button.

I strive to make my functions/handlers small enough that a single  
line of documentation is sufficient. Actually size isn't so much of a  
factor as the single-purpose aspect. If a function or handler has a  
single purpose, generally it can be described in a single sentence.  
Then I include that line as a comment after the definition:

on setupHOOTClasses -- creates an array (sMessageArray) of the  
messages each class can receive
on startHOOT -- initializes HOOT and sets it as a front script

Then there are the handlers that are self-explanatory:

on stopHOOT
on hideNavigator

I've never seen a hundred-line routine that wouldn't be better as  
five twenty-line routines, each of which could be documented with a  
line of code. Perhaps even ten ten-line routines.

regards,

gc