A documentation proposal (non HTML version)

Les Tyrrell tyrrell at canis.uiuc.edu
Mon Jan 21 01:57:09 UTC 2002


----- Original Message -----
From: Duane Maxwell <dmaxwell at san.rr.com>
To: <squeak-dev at lists.squeakfoundation.org>
Sent: Sunday, January 20, 2002 5:34 PM
Subject: A documentation proposal (non HTML version)

> The idea is to make it so easy to submit comments to the system as to be
> something worthwhile to do while browsing code.  If a comment is not
> available for a method or class, a simple click of a "document this" button
> allows a submission.
>
> I will do the backend if someone will do the frontend.  Others can also
> mirror the database in the event of a catastrophic failure.
>
> Comments?

Very tempting... it is easy to imagine expanding this somewhat, but I think it
would be best to keep it restricted to class comments at first.  I think the
FE changes would be fairly simple.  I think it is mostly an issue of deciding
what meta-data to ship along with the comment- timestamps and something to
indicate a version history of the class involved come to mind- for instance,
something I would be interested in being able to determine is how much change
has occurred to a class since the comment was last updated.  In the FE,
classes which have changed substantially since the comment was last updated
could be shown as having documentation that is perhaps a bit untrustworthy...
this information is likely to be a bit discouraging at first. ( actually,
could probably do that from the existing .sources/.changes information ).

As for method comments... generally speaking, if you really feel a method
needs a comment, you're shooting at the wrong problem.   Which is not to say
that being able to look at a view showing only method comments is a bad thing-
just that in many cases perhaps that comment ought to be dynamically inferred
rather than explicitly stated.  I can see something along the lines of "here's
the explicit comment" , or automatically inferring "Answer blob." or "I can't
make heads or tails out of this- what were you thinking?".

- les





More information about the Squeak-dev mailing list