On Sep 12, 2007, at 6:49 AM, Ron Teitelbaum wrote:

> Hi all,
>
> I think it would be nice to have an easier way to modify comments.   
> One or
> more delta streams for comments only would be neat.  (Change a  
> class comment
> and the system should ask you if this comment should be committed  
> to a delta
> stream(s), then the harvesting team could review the comments for  
> inclusion
> or rejection, or when committing code to Monticello the system  
> could ask and
> harvest comments into the delta stream for later review).  The  
> delta stream
> would be good for this because it would help to put the change into  
> context
> and eliminate comments that apply to older squeak images.
>
> There is no real substitute for the original author comments, but  
> once you
> spent the time to figure something out, being able to add comments  
> easily
> may help improve the situation.
>

I feel the system would be dramatically improved by have the  
capability of Package/Category level comments. Currently, even when a  
set of classes do have comments, you still have to wade through the  
classes in order to find out what a good starting place is to use the  
provided functionality. For small class hierarchies this isn't too  
bad, but some are quite large :)

This creates a great place to document the intention of a system and  
provide pointers to other pieces of documentation on classes and  
methods.

This would also prevent having to create specific "documentation"  
classes that do nothing but hold text. For a great example of this,  
see Steven Swerlings SVI package - it contains copious amounts of  
documentation, and uses a class (or classes, I don't remember at the  
moment) to provide access to the docs. But, IMO, it would be better  
as a category level construct.


Would people be interested in such a feature, as long as it could  
work with Monticello and OmniBrowser, for example?

- Brian