first let us start changing the default class comment template to have these sections.
Stef On Apr 24, 2011, at 5:57 PM, Alexandre Bergel wrote: >> for the class comment I would have >> >> intention >> I'm doing that >> collaborations >> with the help of this class and that class >> main api >> my main public API is ... >> >> my subclasses may want to override such specific hooks ... >> >> Implementation notes >> iv and their purposes > > Yes! The collaborations and main api may be automatically inferred (from unit > tests?) > The public interface can also be inferred. > I will work on this. > > Alexandre > > >> >> >>> Hi! >>> >>> I am dreaming about a tool to help me document source code. The question I >>> have is what is a well documented class? >>> What do you think about the following: >>> >>> A well documented class is a class: >>> - that contains a class comment >>> - its class comments contains either an example, or an associated unit test >>> - without 'as yet unclassified' method category >>> - each public method belongs to a method category named public* >>> - each private method belongs to a method category named private* >>> - each method contains a comment, located before the declaration of >>> temporary variables >>> - other methods are considered as "package visible", meaning that they >>> belong to a category that does not begins with 'private' or 'public' >>> - without commented code contained in its methods. >>> >>> Is there anything else? >>> >>> Cheers, >>> Alexandre >>> -- >>> _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: >>> Alexandre Bergel http://www.bergel.eu >>> ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;. >>> >>> >>> >>> >>> >>> >> >> > > -- > _,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;: > Alexandre Bergel http://www.bergel.eu > ^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;._,.;:~^~:;. > > > > > >
