Try to have it so users don't have to delete much, just extend what is there. On Tue, May 12, 2015 at 2:10 AM, Kasper Osterbye <kasper@itu.dk> wrote:
Sergio Fedi and I are now working on this.
As part of the work, we need a "default package comment", akin the the default class comment. The class comment is inspired by CRC idea. Translating CRC to a PRC, we suggest the following, and ask for comments from the community. As I believe we will by the end of the year have a inworld pillar renderer which is fairly stable, the default PRC template could be: 'Please comment me using the following ""template"", ''inspired'' by Class Responsibility Collaborator (CRC) design:
'inspired'' by Class Responsibility Collaborator (CRC) design, written in first-person narrative:
!Package XXX, part of (reference to main package if one exist) one line description: For example, I'm xxx package, containing the hierarchy of visitor objects.
One line description: I'm Xyz package, providing widgets that ... (Leave "Part of package" for Collaborators (see below) )
;Responsibiliies :Three sentences about my main responsibility, what I'm doing, what classes do I offer.
(Three sentences is not much to talk about all the package's classes. How about...) I offer services for ...
;Collaborators
:State my related packages, and which classes are the ones used from the
outside of the package.
I'm part of Abc package ... My related packages are ... My entry points are ...
!!Public API
- message one in class one - message two in class two - what is the way to use this package.
One simple example is simply gorgeous. Or refer to which package is the main package if there are several packages in play
!!Internal Representation and Key Implementation Points.
-Implementation Points, in particular references to classes with good class comments.'
Will this work?
Nice initiative. cheers -ben