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
>
