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
<zelphirkaltst...@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
