buildMicroDownUsing: withComment: should be simplified

[kasperosterbye]

The top template is the one that adds the header with the class name, and inserts the rendered comment.

Hence most subclasses follow this template:

buildMicroDownUsing: aBuilder withComment: aString
	
	super buildMicroDownUsing: aBuilder withComment: aString.
	self addSomeSectionOfRelevanceToSpecificClass: aBuilder

I suggest the implementation in Class is changed to:

buildMicroDownUsing: aBuilder withComment: aString
	
	aBuilder 
		header: [ aBuilder text: 'Class: '.
					aBuilder text: self name ] withLevel: 1;
		horizontalLine;
		text: aString.
	self addDocumentationSections: aBuilder "empty method at class level"

And these methods then follow the pattern of:

addDocumentationSections: aBuilder
	super addDocumentationSections: aBuilder.
	"Add more stuff using aBuilder"

[Ducasse]

I'm too tired now but I was wondering why?

[kasperosterbye]

Good question - I forgot the rationale.
There are two reasons actually:

• The top template is the only thing printing the actual comment, and the idiom accepted elsewhere is to add further stuff after the traditional comment. So rather than specialising a two argument method, of which you only pass the second to the super, I thought it would be simpler to override a method with no 'extra' argument.
• I was thinking it might be nice to let the top template end with a online comment on how to add to the template. Sort of like this:

buildMicroDownUsing: aBuilder withComment: aString
	aBuilder 
		header: [ aBuilder text: 'Class: '.
					aBuilder text: self name ] withLevel: 1;
		horizontalLine;
		text: aString.
	self addDocumentationSections: aBuilder. "empty method at class level"
        aBuilder
                horizontalLine;
		text: 'To add to this template extend the `addDocumentationSections:` method`.