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