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 >> > >> > >> >>
