[squeak-dev] Documentation idea
Bert Freudenberg
bert at freudenbergs.de
Tue Jul 5 15:38:47 UTC 2011
Why not use structured class comments? Seems cleaner to me than littering the system with documentation methods. E.g.
!LayoutMorph commentStamp: 'bf 7/5/2011 17:24' prior: 0!
Collaborators: SystemWindow, MorphExtension, LayoutMorph
Responsibilities: Lay out my submorphs in a row or column
!
!ScrollBar commentStamp: 'bf 7/5/2011 17:24' prior: 0!
Collaborators: ScrollPane, ScrollbarButton, EventHandler
Responsibilities:
Display a scroll bar
Handle my slider being dragged
Ask my model to adjust itself when the user adjusts me
!
#collaborators and #responsibilities would be implemented by parsing the class comment. The browser could be modified to show a CRC card when the comment is rendered.
- Bert -
On 04.07.2011, at 08:31, Rodney Polkinghorne wrote:
> I've been studying the Morphic classes, and today I had an idea on how
> to document them. See the following changeset. Here's an example of
> how it might be used:
>
> SystemWindow collaborators do:
> [:each | HierarchyBrowserWindow
> onClass: each
> selector: nil]
>
> This is obviously just a start. If I expand the notes, do you think
> it would be useful to distribute them? If so, what would be a good
> way to package them?
>
> As a first milestone, I'd like this documentation to be self-hosting.
> I.e., given the CRC cards for an image, a programmer of normal
> intelligence and determination could extend the image with a morph
> that displayed the cards.
>
> Rodney
>
>
> Change set follows:
>
> 'From Cuis 3.3 of 2 June 2011 [latest update: #1024] on 4 July 2011 at
> 4:14:56 pm'!
>
> !LayoutMorph class methodsFor: 'documentation' stamp: 'resp 7/4/2011 16:02'!
> collaborators
> ^Set
> with: SystemWindow
> with: MorphExtension
> with: LayoutMorph! !
>
> !LayoutMorph class methodsFor: 'documentation' stamp: 'resp 7/4/2011 16:13'!
> responsibilities
> "Lay out my submorphs in a row or column"
>
> ^self error: 'Documentation only'! !
>
>
> !ScrollBar class methodsFor: 'documentation' stamp: 'resp 7/4/2011 15:27'!
> collaborators
> ^Set
> with: ScrollPane
> with: ScrollbarButton
> with: EventHandler! !
>
> !ScrollBar class methodsFor: 'documentation' stamp: 'resp 7/4/2011 15:32'!
> responsibilities
> "Display a scroll bar"
> "Handle my slider being dragged"
> "Ask my model to adjust itself when the user adjusts me"
>
> ^self error: 'Documentation only'! !
>
>
> !SystemWindow class methodsFor: 'documentation' stamp: 'resp 7/4/2011 14:06'!
> collaborators
> ^Set
> with: WindowEdgeAdjustingMorph
> with: LayoutMorph! !
>
> !SystemWindow class methodsFor: 'documentation' stamp: 'resp 7/4/2011 14:18'!
> responsibilities
> "Remember and display the window's title"
> "Construct the window's control buttons"
> "Construct WindowEdgeResizingMorphs"
> "Lay out the mophs I construct"
>
> ^self error: 'Documentation only'! !
>
>
> !TextModelMorph class methodsFor: 'documentation' stamp: 'resp 7/4/2011 14:23'!
> collaborators
> ^Set
> with: TextModel
> with: TransformMorph
> with: ScrollBar! !
>
> !TextModelMorph class methodsFor: 'documentation' stamp: 'resp 7/4/2011 14:25'!
> responsibilities
> "Display a pane of externally stored text"
>
> ^self error: 'Documentation only'! !
>
>
> !TransformMorph class methodsFor: 'documentation' stamp: 'resp 7/4/2011 14:28'!
> collaborators
> ^Set new! !
>
> !TransformMorph class methodsFor: 'documentation' stamp: 'resp 7/4/2011 14:31'!
> responsibilities
> "Remember how coordinates relative to a pane correspond to world coordinates"
> "Display the pane in the world"
>
> ^self error: 'Documentation only'! !
>
>
> !WindowEdgeAdjustingMorph class methodsFor: 'documentation' stamp:
> 'resp 7/4/2011 14:54'!
> collaborators
> ^Set
> with: SystemWindow! !
>
> !WindowEdgeAdjustingMorph class methodsFor: 'documentation' stamp:
> 'resp 7/4/2011 14:52'!
> responsibilities
> "Associate resizing cursors with my owner's edges"
> "When I'm dragged, ask my owner to adjust its bounds"
>
> ^self error: 'Documentation only'! !
>
More information about the Squeak-dev
mailing list
|