Re: [Pharo-project] new template for class empty comments for OB

> I see your point. We need to iterate on what a good template can be.
>
> In general, I believe a lot can be extracted from unit test execution that can serve as a good basis for documentation: public, private methods, collaboration, ...
>
> Alexandre
>
>
> On 25 Apr 2011, at 03:15, Lukas Renggli wrote:
>
>> Hi Alexandre,
>>
>>> But this is not incompatible. The IVs may still be listed,
>>> the template can be adjusted for that
>>
>> Yes, this is true and the proposed change takes the IVs into account.
>> The only problem is that I have to scroll to the bottom in 90% of the
>> cases as the variables are a couple of pages below the template text.
>> 90% of the time I am looking for information and then something like
>> the variable types is at least useful, a two page template is only
>> "useful" the few times I actually write a comment.
>>
>> Lukas
>>
>> --
>> Lukas Renggli
>> www.lukas-renggli.ch
>>
>
> --
> _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:
> Alexandre Bergel  http://www.bergel.eu
> ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
>
>
>
>
>

> Hi!
>
> I worked on a small prototype to help me write code documentation.
> As an example, here is a template that is automatically given for MOShape, an abstract class in Mondrian that does not have any class variables. MOShape has just one instance variable, isCached.
>
> -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
> 'MOShape is PLEASE FILL
> MOShape is an abstract class. The following methods needs to be implemented
> #absoluteBoundsFor: #containsPoint:for: #display:on: #heightFor: #widthFor:
>
> Class collaborations
> MOFilledShape MORoundedRectangleShape MOEvent MOLineShape MOAbstractLineLayout MOHorizontalLineLayout MOShape MOVerticalLineLayout MONode MOMouseEvent MOFormsShape MOImageShape MOEasel MOViewRenderer MOShapeAdaptor MOGraphElement MOFormsBuilder MOBoundedShape MOChildrenShape MONodeShape
>
> Testing classes
> MOViewRendererTest MondrianTest MOFormsBuilderTest MONewFormsBuilderTest
>
> Class public API
> #absoluteBoundsFor: #apply:bounds: #boundsFor: #canHandleChildren #collectAllShapes #computeBoundsFor: #computeExtentFor: #containsPoint:for: #disableCache #display:on: #enableCache #heightFor: #isCached #isChildShape #isFormsShape #isLineShape #isNodeShape #isShape #scaleElement:by:
> Implementation notes
>
> Instance Variables:
> isCached --  PLEASE FILL
>
> Comments written by AlexandreBergel on 25 April 2011
> '
> -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
>
> I plan to use this template for each class of Mondrian.
> The template can be easily automatically processed to detect inconsistency.
>
> A collaboration class is a class for which I sent to or received a message from. Unit tests are excluded.
> A public method is a method that is invoked by an instance of a different class. This is very Java specific, I know. We could scope it to an object instead of a class.
>
> What is your opinion on this template?
>
> Cheers,
> Alexandre
>
>
> On 25 Apr 2011, at 11:59, Alexandre Bergel wrote:
>
>> I see your point. We need to iterate on what a good template can be.
>>
>> In general, I believe a lot can be extracted from unit test execution that can serve as a good basis for documentation: public, private methods, collaboration, ...
>>
>> Alexandre
>>
>>
>> On 25 Apr 2011, at 03:15, Lukas Renggli wrote:
>>
>>> Hi Alexandre,
>>>
>>>> But this is not incompatible. The IVs may still be listed,
>>>> the template can be adjusted for that
>>>
>>> Yes, this is true and the proposed change takes the IVs into account.
>>> The only problem is that I have to scroll to the bottom in 90% of the
>>> cases as the variables are a couple of pages below the template text.
>>> 90% of the time I am looking for information and then something like
>>> the variable types is at least useful, a two page template is only
>>> "useful" the few times I actually write a comment.
>>>
>>> Lukas
>>>
>>> --
>>> Lukas Renggli
>>> www.lukas-renggli.ch
>>>
>>
>> --
>> _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:
>> Alexandre Bergel  http://www.bergel.eu
>> ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
>>
>>
>>
>>
>>
>
> --
> _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:
> Alexandre Bergel  http://www.bergel.eu
> ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
>
>
>
>
>
>