unofficial mirror of guile-devel@gnu.org 
 help / color / mirror / Atom feed
* Feature request: Ability to document variables like defvar in elisp
@ 2022-11-02  1:08 Jacob Hrbek
  2022-11-02  8:28 ` Jean Abou Samra
  0 siblings, 1 reply; 5+ messages in thread
From: Jacob Hrbek @ 2022-11-02  1:08 UTC (permalink / raw)
  To: guile-devel

[-- Attachment #1: Type: text/plain, Size: 889 bytes --]

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)

So that it can be called from (help variable):

scheme@(guile-user)> (help variable)
`variable' is a procedure in the (guile) module.
expanded docstring here

This way it will also make it possible to easily implement development environment that shows the documentation on cursor hover.

---

Credit: Inspired by 'defvar' from elisp:

(defvar variable default-value docstring)

-- Jacob "Kreyren" Hrbek

[-- Attachment #2: Type: text/html, Size: 1598 bytes --]

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Feature request: Ability to document variables like defvar in elisp
  2022-11-02  1:08 Feature request: Ability to document variables like defvar in elisp Jacob Hrbek
@ 2022-11-02  8:28 ` Jean Abou Samra
  2022-11-02 10:15   ` Mikael Djurfeldt
  2022-11-05  4:19   ` Jacob Hrbek
  0 siblings, 2 replies; 5+ messages in thread
From: Jean Abou Samra @ 2022-11-02  8:28 UTC (permalink / raw)
  To: Jacob Hrbek, guile-devel

Le 02/11/2022 à 02:08, Jacob Hrbek a écrit :
> 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) => may be #t or #f
(eq? a a) => 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




^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Feature request: Ability to document variables like defvar in elisp
  2022-11-02  8:28 ` Jean Abou Samra
@ 2022-11-02 10:15   ` Mikael Djurfeldt
  2022-11-04 15:10     ` Jean Abou Samra
  2022-11-05  4:19   ` Jacob Hrbek
  1 sibling, 1 reply; 5+ messages in thread
From: Mikael Djurfeldt @ 2022-11-02 10:15 UTC (permalink / raw)
  To: Jean Abou Samra; +Cc: Jacob Hrbek, guile-devel

[-- Attachment #1: Type: text/plain, Size: 1573 bytes --]

(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 <jean@abou-samra.fr> wrote:

> Le 02/11/2022 à 02:08, Jacob Hrbek a écrit :
> > 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) => may be #t or #f
> (eq? a a) => 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
>
>
>

[-- Attachment #2: Type: text/html, Size: 2098 bytes --]

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Feature request: Ability to document variables like defvar in elisp
  2022-11-02 10:15   ` Mikael Djurfeldt
@ 2022-11-04 15:10     ` Jean Abou Samra
  0 siblings, 0 replies; 5+ messages in thread
From: Jean Abou Samra @ 2022-11-04 15:10 UTC (permalink / raw)
  To: mikael; +Cc: Jacob Hrbek, guile-devel


[-- Attachment #1.1: Type: text/plain, Size: 486 bytes --]

Le 02/11/2022 à 11:15, Mikael Djurfeldt a écrit :
> (define a 5)
> (set-object-property! (module-variable (current-module) 'a) 
> 'documentation "The variable a contains a number.")
> ?



Why not, but I wanted to point out that variable documentation
cannot be done in a way that is consistent with procedure documentation.
It needs to be a different mechanism, tied to the module system, which
brings some restrictions (what about local variables?).

Best,
Jean



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 236 bytes --]

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Feature request: Ability to document variables like defvar in elisp
  2022-11-02  8:28 ` Jean Abou Samra
  2022-11-02 10:15   ` Mikael Djurfeldt
@ 2022-11-05  4:19   ` Jacob Hrbek
  1 sibling, 0 replies; 5+ messages in thread
From: Jacob Hrbek @ 2022-11-05  4:19 UTC (permalink / raw)
  To: Jean Abou Samra; +Cc: guile-devel

To clarify I don't want to set the docstring to the value, but to the **variable name** like elisp, defining the docstring to the value seems insane to me.

First of all can we agree that the proposed syntax is a good idea that we want implemented?:

    (define variable value docstring)
                           ^^^^^^^^^

As to me it seems as very logical and intuitive solution.

Then if we can't implement it in guile due to it's current limitations then I propose to track the expected implementation as a bug and in the meantime declare e.g. macro in srfi-X that defines the immeiate and then uses the variable name to set the docstring to the variable name through appropriate code such as the one provided by Mikael Djurfeldt to be e.g. the familiar defvar or even define*:

    (defvar variable value docstring)
    => (define variable value)
    => (set-object-property! (module-variable (current-module) 'variable) 'documentation "Documentation here")

So that the common useless comments above variable definition can be removed from guile scripts and development environments such as https://github.com/Johni0702/guile-language-server adjusted to show the popup in emacs and when guile is able to use the proposed syntax to just s#defvar#define#gm

-- Jacob "Kreyren" Hrbek

------- Original Message -------
On Wednesday, November 2nd, 2022 at 9:28 AM, Jean Abou Samra <jean@abou-samra.fr> wrote:


> Le 02/11/2022 à 02:08, Jacob Hrbek a écrit :
> 
> > 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) => may be #t or #f
> 
> (eq? a a) => 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



^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2022-11-05  4:19 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-11-02  1:08 Feature request: Ability to document variables like defvar in elisp Jacob Hrbek
2022-11-02  8:28 ` Jean Abou Samra
2022-11-02 10:15   ` Mikael Djurfeldt
2022-11-04 15:10     ` Jean Abou Samra
2022-11-05  4:19   ` Jacob Hrbek

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).