From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Mikael Djurfeldt Newsgroups: gmane.lisp.guile.devel Subject: Re: Feature request: Ability to document variables like defvar in elisp Date: Wed, 2 Nov 2022 11:15:31 +0100 Message-ID: References: <890c5ce4-8191-54a6-dcd3-3c4b0f846415@abou-samra.fr> Reply-To: mikael@djurfeldt.com Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="0000000000007d16fb05ec7a1f5c" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="33650"; mail-complaints-to="usenet@ciao.gmane.io" Cc: Jacob Hrbek , "guile-devel@gnu.org" To: Jean Abou Samra Original-X-From: guile-devel-bounces+guile-devel=m.gmane-mx.org@gnu.org Wed Nov 02 11:16:31 2022 Return-path: Envelope-to: guile-devel@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 1oqAnO-0008Yr-Pt for guile-devel@m.gmane-mx.org; Wed, 02 Nov 2022 11:16:30 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oqAmk-0007p5-Jv; Wed, 02 Nov 2022 06:15:50 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oqAmg-0007oZ-Op for guile-devel@gnu.org; Wed, 02 Nov 2022 06:15:46 -0400 Original-Received: from mail-ed1-f49.google.com ([209.85.208.49]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oqAme-0005P5-Dg for guile-devel@gnu.org; Wed, 02 Nov 2022 06:15:46 -0400 Original-Received: by mail-ed1-f49.google.com with SMTP id i21so25658897edj.10 for ; Wed, 02 Nov 2022 03:15:43 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:subject:message-id:date:from:reply-to:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=nCIOOxnucKnaT57S70FjmDX+qdzOj35KnFNM3wYVkTk=; b=bghGql89cYU7Akg6vyCr2va/4b87RUwRzs31vlTC1u9w5YTGEA7DV1+BgeIF2ueHjQ I1MJuqXqcLLmtu/nDwhpAc8Ng1TMhry5vwNVj6JI7N8d3NhEan96VrFuw88GPuDJGr03 rl1XGu2u1o+9GQ9XqAiL76l87/0R86y4+kQ4O7eLMlrP0VLhoY0u/HwT0vRCZsYICMp5 +G4+NPb96JyFB7diQ4mGs2J8gox1RUt3mY5Sxt4rlvGeFHolG46ahcxRx/kNWdO7uDWw 2qQZQPkuofDTT+1f6mdYzlG6ziJOdoRO8ljL1ZxNV0x0O2x/erXv41aIUeeEvOiIC+zh D9nQ== X-Gm-Message-State: ACrzQf35REXPYuRiOBtFP/WBIGYQb/InHnVLbAiBROX5ql4+koFfmRHc OmmGOsLN/SJz5DuHRzTFMBYJ9yvs8I0r7wfJnzM= X-Google-Smtp-Source: AMsMyM7/8uWLZmtwg59IjjooZqlFqYEr1Oy8UWI+zPpAaympZ8Yl3PAv7ZxbWLrMw5Deh97pCijTibvQ7QhQHY3aqrU= X-Received: by 2002:aa7:c9c7:0:b0:463:4eff:a07 with SMTP id i7-20020aa7c9c7000000b004634eff0a07mr16063912edt.88.1667384142008; Wed, 02 Nov 2022 03:15:42 -0700 (PDT) In-Reply-To: <890c5ce4-8191-54a6-dcd3-3c4b0f846415@abou-samra.fr> Received-SPF: pass client-ip=209.85.208.49; envelope-from=mdjurfeldt@gmail.com; helo=mail-ed1-f49.google.com X-Spam_score_int: -15 X-Spam_score: -1.6 X-Spam_bar: - X-Spam_report: (-1.6 / 5.0 requ) BAYES_00=-1.9, FREEMAIL_FORGED_FROMDOMAIN=0.001, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: "guile-devel" Errors-To: guile-devel-bounces+guile-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.lisp.guile.devel:21461 Archived-At: --0000000000007d16fb05ec7a1f5c Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable (define a 5) (set-object-property! (module-variable (current-module) 'a) 'documentation "The variable a contains a number.") ? On Wed, Nov 2, 2022 at 9:29 AM Jean Abou Samra wrote: > Le 02/11/2022 =C3=A0 02:08, Jacob Hrbek a =C3=A9crit : > > The ability to document variables is critical for many projects such > > as libfive where the variables is used to declares functional computer > > aided design structure and other projects where variables influence > > the workflow. > > > > Thus proposing to change the 'define' behavior for variables to > implement: > > > > (define variable default-value docstring) > > ^^^^^^ > > > > Where docstring is optional and in case it's provided to call for > example: > > > > (set-procedure-property! variable 'documentation docstring) > > > > > The problem is that in Scheme, you cannot attach metadata to immediate > values. According to the Scheme standards and the Guile documentation, > > > (define a 5) > (define b 5) > > (eq? a b) =3D> may be #t or #f > (eq? a a) =3D> may be #t or #f > > > So it's considerably more complicated than using an object property, > because that would not work reliably for variables defined to immediates > like numbers and characters. Instead you would need to attach the > metadata to the name you're defining the variable to, like Elisp does, > but unlike Guile does with procedures right now, and it's not as simple > in Scheme due to lexical scoping. > > Best, > Jean > > > --0000000000007d16fb05ec7a1f5c Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
(define a 5)
(set-object-property! (module-= variable (current-module) 'a) 'documentation "The variable a c= ontains a number.")

?

On Wed, Nov 2,= 2022 at 9:29 AM Jean Abou Samra <= jean@abou-samra.fr> wrote:
Le 02/11/2022 =C3=A0 02:08, Jacob Hrbek a =C3=A9crit=C2= =A0:
> The ability to document variables is critical for many projects such <= br> > as libfive where the variables is used to declares functional computer=
> aided design structure and other projects where variables influence > the workflow.
>
> Thus proposing to change the 'define' behavior for variables t= o implement:
>
> =C2=A0 =C2=A0 (define variable default-value docstring)
> =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 = =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2= =A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0 =C2=A0^^^^^^
>
> Where docstring is optional and in case it's provided to call for = example:
>
> (set-procedure-property! variable 'documentation docstring)




The problem is that in Scheme, you cannot attach metadata to immediate
values. According to the Scheme standards and the Guile documentation,


(define a 5)
(define b 5)

(eq? a b) =3D> may be #t or #f
(eq? a a) =3D> may be #t or #f


So it's considerably more complicated than using an object property, because that would not work reliably for variables defined to immediates like numbers and characters. Instead you would need to attach the
metadata to the name you're defining the variable to, like Elisp does,<= br> but unlike Guile does with procedures right now, and it's not as simple=
in Scheme due to lexical scoping.

Best,
Jean


--0000000000007d16fb05ec7a1f5c--