Documentation idea

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'! !

Rodney

I like this idea. Could you provide a screen shot please how this look like?

Regards
Hannes

On 7/4/11, Rodney Polkinghorne <[hidden email]> wrote:

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:

Bert Freudenberg <bert <at> freudenbergs.de> writes:

>
> 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
> !
>

I agree with Bert. Suggestions for the format to use in the class comment:
ASCIIDOC, Markdown, DocBook. DocBook for instance paves the way for HTML and PDF.

On 5 July 2011 22:58, Pascal Vollmer <[hidden email]> wrote:
Markdown seems to be gaining traction: lots of GitHub projects use it,
the StackExchange sites use it, ...

frank