From: "Ricardo G. Herdt" <r.herdt@posteo.de>
To: guile-user@gnu.org
Subject: Re: Indentation with inline comments in Emacs
Date: Mon, 18 Apr 2022 13:33:22 +0000 [thread overview]
Message-ID: <ac0b73e48075801fd357dd8cbe5248da@posteo.de> (raw)
In-Reply-To: <325eca55-eb2d-7a66-b5b8-9e323e3e9fc4@posteo.de>
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
>> <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
next prev parent reply other threads:[~2022-04-18 13:33 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-04-16 12:12 Indentation with inline comments in Emacs Zelphir Kaltstahl
2022-04-16 14:57 ` Jérémy Korwin-Zmijowski
2022-04-17 10:49 ` Zelphir Kaltstahl
2022-04-17 13:44 ` Luis Felipe
2022-04-18 10:48 ` Zelphir Kaltstahl
2022-04-18 13:33 ` Ricardo G. Herdt [this message]
2022-04-18 14:09 ` Luis Felipe
2022-04-18 14:05 ` Luis Felipe
2022-04-17 3:03 ` Taylan Kammer
2022-04-17 11:06 ` Zelphir Kaltstahl
2022-04-17 14:58 ` Maxime Devos
2022-04-18 10:49 ` Zelphir Kaltstahl
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=ac0b73e48075801fd357dd8cbe5248da@posteo.de \
--to=r.herdt@posteo.de \
--cc=guile-user@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).