Most modern (and some not-so-modern) languages have a standard way of attaching documentation to functions and other symbols. For example, in Java documentation looks like this:
/**
* Example method that adds 1 to its argument. The documentation
* is a normal comment that comes before the object that
* is documented, but starts with /** instead of the usual /*.
* The first sentence is the "short description" and should be
* a one-line general description.
*/
int add1(int x)
{
return x + 1;
}
Here is a similar documented function in Lisp:
(defun add1 (x)
"Add the value 1 to the argument.
In Lisp, if the function's first element is a string, then
that string becomes the function's documentation. In Emacs-Lisp
the first row of the documentation is the 'short description',
compared to Java where it's the first sentence."
(1+ x))
Lisp also supports access and modification of docstrings at runtime, which is actually pretty cool. A lot of tools take advantage of this to provide dynamic documentation for the running environment.
I think it would be very neat to have the same thing in GNU APL. One way of supporting this in a fully backward-compatible way is to use the Java model; put the documentation in a comment (with some special tag) before the function. For example:
⍝+ Add the value 1 to the right-hand argument.
⍝ In this simple example, the tag ⍝+ indicates that
⍝ the comment is a docstring.
∇Z←add1 X
Z←X+1
∇
Obviously using comments is not the only way to achieve this. Another way would be to use the Lisp model of having the first command in a function be a no-op string. This code would not do anything if documentation is not supported. For example something like this:
∇Z←add1 X
⊣"Add one to the right-hand argument."
Z←X+1
∇
One could then use some ⎕CR functions to get (and set?) the documentation strings for a given symbol. The Emacs mode can integrate the existing documentation features to dynamically display documentation for symbols at appropriate times.
What do you think about this?
Regards,
Elias