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 <loke...@gmail.com> 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" <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
>> >
>> >
>>
>>
