Re: Indentation with inline comments in Emacs

[Luis Felipe <luis.felipe.la@protonmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 1487 bytes --]

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.

[-- Attachment #1.2: publickey - luis.felipe.la@protonmail.com - 0x12DE1598.asc --]
[-- Type: application/pgp-keys, Size: 1815 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 509 bytes --]