"David T. Lewis" <lewis at mail.msen.com> wrote:
> On Tue, Jul 29, 2003 at 08:39:49PM +0200, Andreas Raab wrote:
> > > Rather than making yet another image-based registry, I think this 
> > > would be a great use for the "annotations" that are part of the 
> > > SMCard. After all, we *do* have a master registry for SM packages 
> > > already.
> > 
> > Fine with me, I was just shooting for the simplest thing that could possibly
> > work ;-) Considering that we have WorldMenu>>registerOpenCommand: it seemed
> > to me that having WoldMenu>>registerPackageCommand: might just be the
> > simplest solution of all.
> 
> Well, if we just need something simple that works, how about:
> 
> 1) Class comments, at least for one or more classes that are obviously
> associated with the SM package in question.
> 
> 2) An agreed naming convention for a class side method category such as,
> well, "documentation". This would be a place to put documentation.
> 
> 3) An agreed naming convention for methods that provide documentation,
> such as MyClass class>>squeakMapPackageInfo.
> 
> The default implemention of squeakMapPackageInfo could be:
> 
> Object class>>squeakMapPackageInfo
>   ^ self comment
> 
> Anyone who does not bother with class comments would get a suitably
> embarrassing "comment template" on SM. By writing at least one class
> comment, a slightly less embarrassing message would be displayed on SM.
> And anyone with sufficient motivation to provide actual documentation
> could do so by hooking something useful into a #squeakMapPackageInfo
> method.
> 
> I'm assuming that most SM entries will include some class that is
> an obvious place to keep the documentation, and that we could invent
> some simple way to associate the squeakMapPackageInfo for that class
> with the SM package and make it available to Squeak Map browsers of
> various sorts.
> 
> This would be practically zero extra work for anybody who documents
> their classes. And I'm betting that someone who can't be bothered with
> class comments is not likely to spend a lot of time updating Yet Another
> High Tech Documentation Tool that is maintained separately from their
> code base. I for one wouldn't do it.

Well, I am not talking about YAHTDT. :-) I am talking about the SM1.1
that I am currently working on. One of the principals here is that the
resources I explained about are separate from the package itself. Both a
good thing and a bad thing depending on the characteristics of what we
want. If we just want a couple of lines of text I agree that it should
be included in the package. And a class comment is fine by me since it
works in all different package formats.

Just add a hack in SMLoader to find those class comments using some
convention and you would be fine. The little World menu choice I
discussed could find those too. Bah, I will hack that one up later today
in fact, just to show what I mean. :-)

> Dave

regards, Göran