Feature request: Ability to document variables like defvar in elisp

Feature request: Ability to document variables like defvar in elisp

[Jacob Hrbek]

[-- 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 --]

Re: Feature request: Ability to document variables like defvar in elisp

[Jean Abou Samra]

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

Re: Feature request: Ability to document variables like defvar in elisp

[Mikael Djurfeldt]

[-- 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 --]

Re: Feature request: Ability to document variables like defvar in elisp

[Jean Abou Samra]

[-- 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 --]

Re: Feature request: Ability to document variables like defvar in elisp

[Jacob Hrbek]

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