What is a well documented class?

>
> If we agree on my suggestions, we can compose a set of guidelines to arrive at deliverables that comply with them.
>
> One tool could be a template and a checklist to help the writer of the documentation.
>
> --
> Cesar Rabak
>
> Em 25/04/2011 14:59, Alexandre Bergel < [hidden email] > escreveu:
> Ok, but what would be a tool that help you write comment? This cannot be the system browser.
>
> Alexandre
>
>
> On 25 Apr 2011, at 12:37, [hidden email] wrote:
>
>> I think a well documented class is a class which can be understood by reading its documentation without having to resort to anything else, be it running the test only to see something not obvious, reading the code to understand the working which the document fell short; and without having to assemble a mini encyclopedia of references in order to grasp the contents of the documentation.
>>
>> my 0.019999
>>
>> --
>> Cesar Rabak
>>
>
> --
> _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:
> Alexandre Bergel  http://www.bergel.eu
> ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
>
>
>
>
>
>
>
>

> 2cents about "what is a well-documented class?":
>
> Information about the state variables (instance variables): what goes in the
> slot, and what it's for.
>
> Good examples (the layout gets skewed doing copy/paste)
>
> in RxsPredicate
>
> Instance Variables:
>
> predicate <BlockClosure> A one-argument block. If it evaluates to the value
> defined by
> <negated> when it is passed a character, the predicate is considered to
> match.
>
> negation <BlockClosure> A one-argument block that is a negation of
> <predicate>.
>
>
> SMxMorph
>
> Structure:
> instance var Type Description
> bounds Rectangle A Rectangle indicating my position and a size that will
> enclose me.
>
> owner SMxMorph My parent SMxMorph, or nil for the top-level SMxMorph,
> which is a
> or nil world, typically a SMxPasteUpMorph.
>
> submorphs Array My child Morphs.
>
> fullBounds Rectangle A Rectangle minimally enclosing me and my
> submorphs.
>
> color Color My primary color. Subclasses can use this in different
> ways.
>
> extension SMxMorphExtension Allows extra properties to be stored without
> adding a
> or nil   storage burden to all morphs.
>
>
> --
> View this message in context: http://forum.world.st/What-is-a-well-documented-class-tp3470956p3474024.html
> Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
>

> 2cents about "what is a well-documented class?":
>
> Information about the state variables (instance variables): what goes in the
> slot, and what it's for.
>
> Good examples (the layout gets skewed doing copy/paste)
>
> in RxsPredicate
>
> Instance Variables:
>
> predicate A one-argument block. If it evaluates to the value
> defined by
>  when it is passed a character, the predicate is considered to
> match.
>
> negation A one-argument block that is a negation of
> .
>
>
> SMxMorph
>
> Structure:
> instance var Type Description
> bounds Rectangle A Rectangle indicating my position and a size that will
> enclose me.
>
> owner SMxMorph My parent SMxMorph, or nil for the top-level SMxMorph,
> which is a
> or nil world, typically a SMxPasteUpMorph.
>
> submorphs Array My child Morphs.
>
> fullBounds Rectangle A Rectangle minimally enclosing me and my
> submorphs.
>
> color Color My primary color. Subclasses can use this in different
> ways.
>
> extension SMxMorphExtension Allows extra properties to be stored without
> adding a
> or nil   storage burden to all morphs.
>
>
> --
> View this message in context: http://forum.world.st/What-is-a-well-documented-class-tp3470956p3474024.html
> Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
>

>
>
> Em 25/04/2011 18:19, Alexandre Bergel < [hidden email] > escreveu:
> Ok, focusing on the instance variables. I think there is two kind of documentation, one for the casual user, and another for the developers.
>
> Alexandre
>
>
> On 25 Apr 2011, at 16:09, DougEdmunds wrote:
>
>> 2cents about "what is a well-documented class?":
>>
>> Information about the state variables (instance variables): what goes in the
>> slot, and what it's for.
>>
>> Good examples (the layout gets skewed doing copy/paste)
>>
>> in RxsPredicate
>>
>> Instance Variables:
>>
>> predicate A one-argument block. If it evaluates to the value
>> defined by
>> when it is passed a character, the predicate is considered to
>> match.
>>
>> negation A one-argument block that is a negation of
>> .
>>
>>
>> SMxMorph
>>
>> Structure:
>> instance var Type Description
>> bounds Rectangle A Rectangle indicating my position and a size that will
>> enclose me.
>>
>> owner SMxMorph My parent SMxMorph, or nil for the top-level SMxMorph,
>> which is a
>> or nil world, typically a SMxPasteUpMorph.
>>
>> submorphs Array My child Morphs.
>>
>> fullBounds Rectangle A Rectangle minimally enclosing me and my
>> submorphs.
>>
>> color Color My primary color. Subclasses can use this in different
>> ways.
>>
>> extension SMxMorphExtension Allows extra properties to be stored without
>> adding a
>> or nil   storage burden to all morphs.
>>
>>
>> --
>> View this message in context: http://forum.world.st/What-is-a-well-documented-class-tp3470956p3474024.html
>> Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
>>
>
> --
> _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:
> Alexandre Bergel  http://www.bergel.eu
> ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
>
>
>
>
>
>
>
>

>
> Stéphane Ducasse wrote:
>>
>>
>> yes but.... let us write more comments.
>> All the rest is arguments not to write them which is far easier as usual.
>>
>> Stef
>>
>
> Absolutely.  Sorry, I didn't mean to imply otherwise.
>
> Mike
>
> --
> View this message in context: http://forum.world.st/What-is-a-well-documented-class-tp3470956p3475730.html
> Sent from the Pharo Smalltalk mailing list archive at Nabble.com.
>