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

[Mikael Djurfeldt]

(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