[PERCEPS] wanted ! (new features)

Stefan Seefeld seefelds@MAGELLAN.UMontreal.CA
Sat, 26 Jun 1999 15:31:18 -0400


Mark Peskin wrote:
> 
> > Date: Fri, 25 Jun 1999 20:31:24 +0000
> > From: Stefan Seefeld <seefelds@MAGELLAN.UMontreal.CA>
> > To: "'Perceps'" <perceps@server.python.net>
> > Subject: [PERCEPS] wanted ! (new features)
> >
> > playing around with perceps I wonder whether the
> > following two features would be possible:
> >
> > * adapt the output strategy to the user's needs
> >   (for example not file per class but file per sub project (package))
> 
> This type of thing is already possible, in theory at least, using the global
> variable feature. You can asssign global values to classes as needed, and
> you can produce output files on a per-global-variable-value basis (you can
> even define multiple globals to provide different views of your class
> structure, if you want). My impression is that this feature is not used very
> much, but it can be quite powerful.

Thank's, I'll have a look at it.

> >
> > * document groups of methods
> >   - find a way to tell perceps to consider a set of methods to
> >     be documented as a set since often accessor etc. methods
> >     can have different signatures but almost equal meaning so
> >     having to document each of them individually is completely redundant
> >
> 
> I agree that this would be a good feature to simplify documentation.
> However, in order to be useful it would have to be highly configurable. One
> possible solution that comes to mind is to have a special comment type or
> signature that acts as a "reference" to another "master" member in the
> class. The master and all the members that refer to it could then be
> documented as a group using the master's comment data. This would also
> require some extensions to the template language to allow access to related
> members. For example:
> 
> {foreach public master} <- "master" modifier to foreach loop excludes
> sub-memb.
> .....
> {foreach related}       <- "related" loops over related members
> .....
> {next}
> {next}
> 
> Tom should have fun with this one.

Oh, I thought of something much simpler. My inspiration comes from
the Fresco docs. Their header look like:

//+ some comment here
void method1();
void method2(...);
//. here comes the description for method1 and method2

Well, it's less flexible than your approach but it's sufficient for
my purpose. The '//+' acts like a bracket so when the documentation starts
with '//.' you simply take all methods in between. Sure, now you have to
group methods together in the class definition, too. But that's most frequently
done anyway, if the methods have a common purpose.

Anyway, just some ideas...

Stefan