Thank you. I didn't think of doing that. I will fix that today. Regards, Elias On 17 Jul 2014 08:02, "David Lamkins" <da...@lamkins.net> 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 <loke...@gmail.com> > 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 <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 >>>> > >>>> > >>>> >>>> >> > > > -- > "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/ >