And here I am, replying to myself instead of actually thinking through everything before posting. Oh well...
I'd say that I personally prefer the last form. The reason for that is that this actually translates to one-line lambda functions quite nicely. Here's the one-line version of the last example: add1 ← { "Add one to the right-hand argument." ⊢ ⍵+1 } Regards, Elias On 14 July 2014 00:01, Elias Mårtenson <loke...@gmail.com> wrote: > 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 >