I like this idea a lot. Having the comment inside the function allows you
to edit the text when using the Emacs function editor. If the comment is
outside, it won't be part of the function per se.
Secondly, as David pointed out, one can already access the comment from APL
if it is inside the function. I never thought of that. This means that I
can access this without any support code needed from GNU APL itself.
I'll implement something for this soon. :-)
Regards,
Elias
On 14 Jul 2014 08:53, "David B. Lamkins" <da...@lamkins.net> wrote:
> Common Lisp has doc strings as part of the language definition. There's
> a mechanism defined as part of the language to read the doc string and
> stash it in the function definition so that the appropriate access
> functions can find it.
>
> There's really no equivalent to this in APL. A function definion is
> nothing more that an undifferentiated sequence of lines that may be
> either code, comment or code followed by a comment.
>
> Perhaps it's sufficient to rely upon a combination of convention and
> tools. Assume that the header comments for a function (i.e. all of the
> comment lines preceding the first statement) form its documentation;
> optionally take the first line of the header comment as a "short
> description". (The latter might be problematic in the case that one uses
> Emacs' fill function on the comment. OTOH, I suppose that one might
> insert an empty comment line between the short description and the rest
> of the header comment.)
>
> I'm not a fan of inserting markup language into comments. That'd apply
> to your proposal for for using ⍝+ to mark a docstring. I'd prefer to
> assume that the comment line(s) following the function header is (are)
> the docstring.
>
> As regards the extended ⎕CR functions: all of this can be easily
> implemented using defined functions; no need to extend the built-in
> functions. Take advantage of the position of the header comment to
> either read or modify that comment using a simple utility based upon ⎕CR
> and ⎕FX.
>
>
> On Mon, 2014-07-14 at 00:04 +0800, Elias Mårtenson wrote:
> > 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
> >
> >
>
>
