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

Stéphane Ducasse stephane.ducasse at inria.fr
Tue Apr 26 11:29:25 CEST 2011


the problem of automated is that your would like aslo to know the roles of the class during its interaction.
But this could be something to start

about the collaboration may be you should only show roots when you have root and leaves.

stef
On Apr 25, 2011, at 10:25 PM, Alexandre Bergel wrote:

> 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
> ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;.
> 
> 
> 
> 
> 
> 




More information about the Pharo-project mailing list