unofficial mirror of guile-user@gnu.org 
 help / color / mirror / Atom feed
From: Zelphir Kaltstahl <zelphirkaltstahl@posteo.de>
To: Luis Felipe <luis.felipe.la@protonmail.com>
Cc: guile-user@gnu.org
Subject: Re: Indentation with inline comments in Emacs
Date: Mon, 18 Apr 2022 10:48:29 +0000	[thread overview]
Message-ID: <325eca55-eb2d-7a66-b5b8-9e323e3e9fc4@posteo.de> (raw)
In-Reply-To: <AcTGbEepolZj7RpRZwxyb7OsOkzc4wxj2DDuqkC6Gywsfs_---wvEigSi_EO8EitjMTyabIfyeiynuz667oBDvtZwdFowg--y3JmEmO_3jM=@protonmail.com>

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

-- 
repositories: https://notabug.org/ZelphirKaltstahl




  reply	other threads:[~2022-04-18 10:48 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 [this message]
2022-04-18 13:33         ` Ricardo G. Herdt
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=325eca55-eb2d-7a66-b5b8-9e323e3e9fc4@posteo.de \
    --to=zelphirkaltstahl@posteo.de \
    --cc=guile-user@gnu.org \
    --cc=luis.felipe.la@protonmail.com \
    /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).