Thank you. I didn't think of doing that. I will fix that today.
Regards,
Elias
On 17 Jul 2014 08:02, "David Lamkins" <[email protected]> wrote:
> 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 <[email protected]>
> wrote:
>
>> And it's completed. C-c C-h on a function should now display its
>> documentation (if there is one).
>>
>> Regards,
>> Elias
>>
>>
>> On 14 July 2014 09:17, Elias Mårtenson <[email protected]> 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,
>>> Elias
>>> On 14 Jul 2014 08:53, "David B. Lamkins" <[email protected]> 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 <[email protected]> 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
>
>
> http://soundcloud.com/davidlamkins
> http://reverbnation.com/lamkins
> http://reverbnation.com/lcw
> http://lamkins-guitar.com/
> http://lamkins.net/
> http://successful-lisp.com/
>
