guile-user
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Indentation with inline comments in Emacs


From: Ricardo G. Herdt
Subject: Re: Indentation with inline comments in Emacs
Date: Mon, 18 Apr 2022 13:33:22 +0000

Hi Zelphir,

actually the doc-strings are available during runtime using '(ice-9 documentation)', so theoretically it is not restricted to Emacs. In fact I have been working on my spare time on a LSP server for scheme (together with a emacs-lsp and a VS Code extension), and documentation of guile functions was quite straight-forward to implement. It's not yet ready for prime time though.

Regards,

Ricardo

Am 18.04.2022 12:48 schrieb Zelphir Kaltstahl:
Hello Felipe!

On 4/17/22 15:44, Luis Felipe wrote:
Hi Zelphir,

On Sunday, April 17th, 2022 at 10:49 AM, Zelphir Kaltstahl <zelphirkaltstahl@posteo.de> wrote:

I have the same indentation issue though, when I use #||# comments for arguments, which are not keyword arguments, but I want to hint what they are used for. One could argue, that I should rewrite the called function to use keyword arguments, or, if it is a library function, I should wrap it. Hmmm.
Maybe that's a valid point.
Or document the function and its parameter using a documentation string (docstring) instead of comments? This way, you or the users of your code can read that documentation with Emacs Geiser.

For instance:

(define (get-field record field)
   "Get the value of FIELD from RECORD.

   RECORD (Guile Record or SRFI 9 Record)
     A record of any type.

   FIELD (Symbol)
     The name of the field.

   RETURN VALUE (Anything)
     The value of the field.

   If the FIELD does not exist, a no-such-field exception is raised."
   (let* [(descriptor (record-type-descriptor record))
          (access-field (record-accessor descriptor field))]

     (access-field record)))

Then, in Emacs, when calling this procedure, you would place the caret in get-field, press C-c C-d C-d, and Emacs would show its documentation in a buffer.

That's my documentation style, though, which is not conventional, but just an example.

Using documentation string is also useful if you later want to [auto]generate API documentation.

It is a good idea to document ones code, of course, even for future self : )

Usually when I `M-x run-geiser RET` or `M-x run-geiser RET` and then
move the cursor into a function call and the function is somehow
available to Geiser, I see a line at the bottom of my Emacs, which
lists the arguments and highlights the argument, which I should be
filling in next. That is already very helpful.

However, this is all assuming, that everyone uses Emacs. Comments
would be more universally accessible. (I know it sounds almost crazy
not to use Emacs for coding Guile ;D) That would help others, who do
not use Emacs as well.

I like the documentation style in the doc string you are proposing.
Not sure I will always go to that length myself, but it would probably
be a good practice. Just like you said, for generating auto-generating
things like API docs. Btw.: What is the standard tool in the Guile
ecosystem to do that from doc strings like yours?

Also thanks for the C-c C-d C-d hint. I did not know the shortcut.

Best regards,
Zelphir



reply via email to

[Prev in Thread] Current Thread [Next in Thread]