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
