Hi Zelphir, On Sunday, April 17th, 2022 at 10:49 AM, Zelphir Kaltstahl <[email protected]> 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.
publickey - [email protected] - 0x12DE1598.asc
Description: application/pgp-keys
signature.asc
Description: OpenPGP digital signature
