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: Zelphir Kaltstahl
Subject: Re: Indentation with inline comments in Emacs
Date: Mon, 18 Apr 2022 10:48:29 +0000

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

--
repositories: https://notabug.org/ZelphirKaltstahl




reply via email to

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