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.