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/
