From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: "Ricardo G. Herdt" Newsgroups: gmane.lisp.guile.user Subject: Re: Indentation with inline comments in Emacs Date: Mon, 18 Apr 2022 13:33:22 +0000 Message-ID: References: <675f8207-b178-6cbf-24a0-6e4e53a057f2@posteo.de> <2BCF2B67-B2D8-480F-BA1C-D9A8580914FB@korwin-zmijowski.fr> <591cc2fe-6aec-37f4-4eb5-170c713b8ac1@posteo.de> <325eca55-eb2d-7a66-b5b8-9e323e3e9fc4@posteo.de> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="35808"; mail-complaints-to="usenet@ciao.gmane.io" To: guile-user@gnu.org Original-X-From: guile-user-bounces+guile-user=m.gmane-mx.org@gnu.org Mon Apr 18 15:33:42 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 1ngRVd-00094v-LT for guile-user@m.gmane-mx.org; Mon, 18 Apr 2022 15:33:41 +0200 Original-Received: from localhost ([::1]:55860 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1ngRVc-00026T-K7 for guile-user@m.gmane-mx.org; Mon, 18 Apr 2022 09:33:40 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:32872) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ngRVR-00026L-3V for guile-user@gnu.org; Mon, 18 Apr 2022 09:33:29 -0400 Original-Received: from mout02.posteo.de ([185.67.36.66]:50331) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1ngRVO-0004jI-Vy for guile-user@gnu.org; Mon, 18 Apr 2022 09:33:28 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id C958C24010A for ; Mon, 18 Apr 2022 15:33:23 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.de; s=2017; t=1650288803; bh=cMABaZKbV1F0bSXMxNADFhMp+EVgMgk+6KMdAsHnZyI=; h=Date:From:To:Subject:From; b=mKHoOZTgYXkuX0ON8MmCL+QQenpcP3HYSixJUlrOhUfG1sWWHg+uS5gORNHBVuCXX JJ31ZioV9Z+rdfHf3pdpd67Vo42AvBDl4ucsckriVaj6mgnwlvLu6xK8zy1FpgEcY2 L1GbYBEmXQoKjQYVnNLEPp/6oH/2THaxNfYi4NOnruCrJqoMAMULy1hfLWmFIAV3Iv nyQqGnaKlBGOiKu6I4Ct8c8O7vwTPqettqKfuyKRXm3GunHaIchl3QKIVYrnjn3/1v I5t5sKED8KOd0f3rdZZJwwko14reGY+aJ9Jatn6FWJMTvzUp5SfWxFbVWvUCOZ9L3p pY5mm5L4+m5uQ== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4Khnv71qRWz9rxH for ; Mon, 18 Apr 2022 15:33:23 +0200 (CEST) In-Reply-To: <325eca55-eb2d-7a66-b5b8-9e323e3e9fc4@posteo.de> Received-SPF: pass client-ip=185.67.36.66; envelope-from=r.herdt@posteo.de; helo=mout02.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:18253 Archived-At: 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 >> 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