[PD] do we need more self-documenting mechanisms?

[Krzysztof Czaja]

hi all,

the max-like reference patches will always remain the main source
of information and the best self-documenting feature.  But keeping
them up-to-date is a challenge, especially for someone who simply
wants to share externals with others.  There will always be
missing, unfinished or obsolete references.

There is even greater problem with `0.INTRO.txt' reference, which
is now the only way to list (nearly) all of the builtin classes.
How many users know of an obscure midiclkin builtin?  How about
listing all loaded externals?  Or producing an up-to-date list of
all the messages one can send to pd or to a canvas -- or to any
other object -- without greping the sources?

A simple mechanism used for listing all messages of a class, would
not require introducing any fundamental changes to the program, and
would provide a nice self-documenting feature.  One may think of
many ways to extend such a mechanism, but for the time being the
very basics would need to be choosen from among at least three
options:

1. Reserve a selector (like: help, info or messagelist), define
a default method for this selector, and add this method during
creation of any class (excluding messresponder and designing
a special version of the method for objectmaker).  This option is
very easy -- I have managed to make a working prototype -- but
has many flaws.

2. Create a special class (`help' or `info') and for any new class
add a method to this info-class with a selector named after the
new class.  Sending 'info' to an info-object would list all the
known classes.  This option could be tricky.

3. Add several self-documenting messages to pdclass, possibly
assigning some gui items to them.

Krzysztof

Btw. do you know what is advertised as ``advanced,
self-documenting, customizable, extensible and real-time''?
Hint: there are many among us on pd-list, that use it everyday.
Another hint: no, it is not PureData :-)