PackageDescription: BetterComments


Better Comments

Last published: February 9, 2010 by 'thawker1'

Defines 0 Classes
Extends 1 Classes

The BetterComments package contains extensions to BrowserCommentTool to look for more things to detect in the default comment generator. The revisions to the comment tool for VW7.7 provided pretty formatting so that the standard comment section names (such as "Instance Variables:") are emboldened to look like section headings. The browser emphasis routine looks for quite a few more section names than what is built by the default comment generator. This package augments the generator by specifying the types of sections by pragmas (method annotations) with an ordering argument. Methods containing the pragma are invoked, in order, to build that section in the comment, if applicable.

The VW7.7 comment capabilities, along with this package, can be readily extended for your own purposes:
1. You can override the value of the pragma argument to get a different order of sections.
3. You can define new sections to be recognized and formatted.
2. You can add new methods to build new sections.

You define new section headings to be recognized by adding a class method with the pragma . This method returns an ordered collection of the section heading string without a trailing colon; see the #standardSectionHeadings class method. The comment formatting logic looks for lines that contain only the characters in one of the supplied strings, with an optional trailing colon. Those it finds will be emboldened in the output display.

You generate new sections by adding instance methods with the pragma , where rank is an integer that specifies the order in which the section will appear in the output. The method takes two arguments: the first is the class (not the behavior) that is to examined, and the second is the stream onto which the section should be written. By convention, all methods start with the verb "print", followed by an optional word "Class" to indicate that it looks at class behavior rather than instance behavior, followed by words that indicate what is being generated. This concludes with the suffix keyword 'For:', the first argument, then the keyword 'on:', with the stream as second argument. For example, #printInstanceVariablesFor:on: and #printClassInstanceVariablesFor:on:.