|
| From: | Elias Mårtenson |
| Subject: | Re: [Bug-apl] Formal format for function documentation |
| Date: | Thu, 17 Jul 2014 08:27:37 +0800 |
Thank you. I didn't think of doing that. I will fix that today.
Regards,
Elias
Picking up the function name at point doesn't quite work; it stops at _. You may want to make sure that all valid APL break characters {_⍙∆¯} are recognized.Did you consider trimming the local variables list? To me, that doesn't seem especially useful in a documentation buffer.
On Wed, Jul 16, 2014 at 3:38 AM, Elias Mårtenson <address@hidden> wrote:
And it's completed. C-c C-h on a function should now display its documentation (if there is one).Regards,EliasOn 14 July 2014 09:17, Elias Mårtenson <address@hidden> wrote: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,
EliasOn 14 Jul 2014 08:53, "David B. Lamkins" <address@hidden> 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 <address@hidden> 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
>
>
--"The secret to creativity is knowing how to hide your sources."Albert Einstein
| [Prev in Thread] | Current Thread | [Next in Thread] |