From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Zelphir Kaltstahl Newsgroups: gmane.lisp.guile.user Subject: Re: Indentation with inline comments in Emacs Date: Mon, 18 Apr 2022 10:48:29 +0000 Message-ID: <325eca55-eb2d-7a66-b5b8-9e323e3e9fc4@posteo.de> References: <675f8207-b178-6cbf-24a0-6e4e53a057f2@posteo.de> <2BCF2B67-B2D8-480F-BA1C-D9A8580914FB@korwin-zmijowski.fr> <591cc2fe-6aec-37f4-4eb5-170c713b8ac1@posteo.de> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="3023"; mail-complaints-to="usenet@ciao.gmane.io" Cc: guile-user@gnu.org To: Luis Felipe Original-X-From: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Mon Apr 18 12:48:52 2022 Return-path: Envelope-to: guile-user@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1ngOw8-0000aO-9K for guile-user@m.gmane-mx.org; Mon, 18 Apr 2022 12:48:52 +0200 Original-Received: from localhost ([::1]:39198 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ngOw6-0008FY-Q9 for guile-user@m.gmane-mx.org; Mon, 18 Apr 2022 06:48:50 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:60330) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ngOvt-0008F8-5I for guile-user@gnu.org; Mon, 18 Apr 2022 06:48:37 -0400 Original-Received: from mout01.posteo.de ([185.67.36.65]:34479) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ngOvq-0002TF-JC for guile-user@gnu.org; Mon, 18 Apr 2022 06:48:36 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id 6090A240029 for ; Mon, 18 Apr 2022 12:48:31 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.de; s=2017; t=1650278911; bh=jrGHyZys938ljY37I6OqTXJFUQaQD10f/PlI/3FfZZ0=; h=Date:Subject:To:Cc:From:From; b=n48RuFyj3bKrwoi8+KSQ7dm37KdbgPXHJDCD+hyaKbrHAv6lJnRXZ2qplMcsP/ORj maaUO5OduejGY719ApoI8P0MJrjOVBnx8QqjHZtpPSEMSZZu5sCKbpqNpqpiLyuvQT YRstS42xSD3QKERVOzwBczf1e+bhu8hNMEZGdlIiaxrJaD2Ir0AZkcpRzbB9Di4oJe 2jTbmLsaBOTKB/Q0WsFbDoUsz7xE9Wiujw10kybaFLldAyq2O+3hikLqBwbC+dYTGK Au/j6QagBF6JHMqM3bHJl20HNF+0fMvM2FUzOvdEdEDQk7QE0nmtQoEijqs8LRi2Q5 RHORsJTCrUBTA== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4KhkDt18j1z9rxL; Mon, 18 Apr 2022 12:48:30 +0200 (CEST) Content-Language: en-US In-Reply-To: Received-SPF: pass client-ip=185.67.36.65; envelope-from=zelphirkaltstahl@posteo.de; helo=mout01.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Original-Sender: "guile-user" Xref: news.gmane.io gmane.lisp.guile.user:18251 Archived-At: Hello Felipe! On 4/17/22 15:44, Luis Felipe wrote: > Hi Zelphir, > > On Sunday, April 17th, 2022 at 10:49 AM, Zelphir Kaltstahl 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