> Hi Duane,
>
> I was working on a special documentation SWiki which will generate
> documentation form pages from the comments inside and update the comments
> within itself with the web interaction. It is not ready yet and with my
load
> won't be ready at least until after we released the big double issue but
it
> seems a very promising tool for collecting and updating class and method
> comments as well as comments for class and method categoriescategories and
> variable comments. Updating other images becomes a matter of saving the
> change set and loading it from other images. Unfortunately as is it is
prone
> to crash because it keeps changing itself . There are some issues
including
> security issues we we haven't even begun to address but I believe all of
> these can be addressed.
>
> With category comments this information can automatically be turned into a
> quite detailed reference manual that can be ( Dandelion can already do
that
> and we will soon have more tools! ) automatically generated each time it
is
> needed from Squeak directly. Keep tuned for more fancy toys!
>
> Can you host SWikis in your machine?
>
> I may as well make the announcement for our on-demand publishing venture
in
> the next email.
>
> Cheers,
>
> Tansel

While I can see how this might be useful for documenting a particular image,
I don't see how this would solve the problem I'm trying to address -
consolidating the incremental documentation from a large number of users
across a number of images.  Also, in the case of method comments, I'm not
sure that comments of the type:

x := 1.  "initialize counter"

are very helpful and worth collecting.  I'm thinking of stuff like:

"This method increments the number of children in the tree.  It should
probably not be called directly - you should use MyClass>>addChild instead."

To Les's points regarding the need for method comments, I think there's
still some need for some commentary about the intent of methods
(particularly since Smalltalk has no notion of private/protected/public
scope).  A method that does not require documentation need not have any, and
therefore have no entry in the database, so I would not exclude the feature
because only a few methods deserve it.

Also keep in mind that I'm not talking about an automated way to update the
image - beyond some local caching for efficiency reasons, the documentation
is fetched from the server whenever the class or method is browsed.  That
way everyone has more or less the same version for the same image/update at
the same time.

I guess I probably should not have used the word "comments" in my original
email, but rather  stressed "documentation" on a method/class basis.  This
might (optionally) show up as a separate pane in the browser.

To Tim's point about higher level views, I agree there's also a strong need
that Swikis would seem to address but apparently don't, but that's a
different problem.

My goal is to help a new user (both the Squeak newbie or someone just
investigating an unfamiliar class for the first time) with archaeology.  I
guess I'm also trying to decouple the documentation from the image since the
existing mechanism, changesets, don't differentiate between code and comment
changes, are overly tedious to create, and don't propagate quickly enough.

I *could* host a Swiki on my servers, but I'm not sure I'm inclined to.  I'm
concerned that Swikis are not equipped to serve the substantial amount of
traffic I would expect with this mechanism.

-- Duane