[ENH]browserNagIfNoClassComment (v5)

Karl Ramberg karl.ramberg at chello.se
Thu Oct 30 09:45:05 UTC 2003



Markus Gaelli wrote:
> 
> Hi Doug,
> 
> > This is looking better, although I think I prefer having the comment
> > show up in double-quotes below the template as in your previous
> > changeset, rather than extending the template method to
> > #subclass:instVarNames:...comment:, for a couple of reasons:
> >
> > - It looks a bit better visually to have a multi-line comment start on
> > a new line (with an extra cr in between).
> So why not
> 
> Class >>
>         instanceVariableNames: someVarNames
>         classVariableNames: someClassNames
>         poolDictionaries: somePoolDics
>         category: categoryName
>         comment:
> aCommentText
This is easy to fix. It's just to ass a extra cr.
> 
> This shows in the creation method of a class that
> it is _essential_ for it to have comments.

> > - You have to worry about escaping or handling extra single quotes
> > when accepting a new comment in the definition pane.  Hm, it looks
> > like this is handled with some sort of magic in your changeset, but
> > this causes some weirdnesses, such as if you put a space after
> > comment: (to make it consistent with the other parameters), it inserts
> > a new single-quote.
> I think this is a solvable technical problem, just keep the text
> as long as Text as possible, it was not needed until
> now and can be done in a more elegant and possibly
> more error-free way than I did in my little hack.
> > Also, I think the inform: pop-up isn't as necessary if we have the
> > comment in the definition pane, as long as there is some warning text
> > if the comment is missing.  The pop-up message unfairly punishes
> > innocent newbies who simply want to browse code, and will probably
> > scare people away. :)
> I think that Karl wants to put this to "default on" only in
> "images in-between" so that would be o.k. for me.
Exactly. Running in alpha and beta is only for daredevils:-)
> >
> > So, I'd personally be happy to approve a changeset which:
> >
> > - Has the inform pop-up and preference removed.
> > - Shows the class comment (in read-only mode)
> I believe that Karl and me had both the idea to make it writable
>   in the class definition pane independent from each other...
> Still think that this would lower the barrier to write comments,
> and this is what this change-sets are all about, no?
Yes, I think authoring should always be on.
> 
> > - If there is no class comment, the quoted part in the definition pane
> > would say something like "This class has no comment!"
> Yep, that should be the empty/ default comment.
Fixed.
> > - Escape any double-quotes in the comment by doubling them in the
> > definition pane. (otherwise a class comment containing double-quotes
> > will mess things up when you add instvars, etc.
> Don't know about this one right now.
I'll look into it. 
> Karl?
> 
> Markus
> 
> >>>> The snag with both is that the comments are in read only
> >>>> mode but in 'comment mode'.
> >>>> I'm not sure how to fix that.
> >>>>
> >>>
> >>> I did a little hack, which should do the trick...
> >>> though not as I naively thought by enhancing
> >>> Class with something like >> subclass: '' instVarNames: '' (...)
> >>> comment: ''
> >>>
> >>> The reason is, that the Class >> classComment: '' expects a text and
> >>> not
> >>> a string. (' in strings are ugly to write and read...)
> >>>
> >>> So I hacked
> >>> Browser >> defineClass: defString notifying: aController
> >>>
> >>> which is already to long....:-(
> >>>
> >>> I still reformated it like it could be a method sent to class,
> >>> maybe this is missleading?
> >>>
> >>> Attention: I did not look into timestamps issues of the comment, so
> >>> this might be wrong.
> >>> Also the comment does not update while on the class side...
> >>> Also no tests.
> >>>
> >>> So there is room for improvement... ;-)
> >>>
> >> Thanks, this is starting to look good.
> >>
> >> I fixed a issue with a single quote being added to the end of each
> >> comment.
> >>
> >> Karl
> >>
> >> <NagIfNoClassComment.9.cs.gz>
> >
> >



More information about the Squeak-dev mailing list