Typo in defconst-1 and defvar-1 docstrings?

Typo in defconst-1 and defvar-1 docstrings?

[Philip Kaludercic]

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


I was reading through the implementation of defconst-1, but was confused
by the docstring that states:

   More specifically behaves like (defvar SYM 'INITVALUE DOCSTRING).

Isn't the point of defconst-1 as a functional variant of defconst, that
SYM will evaluate to a symbol?  And why should INITVALUE be quoted?
Unless I am mistaken, this patch ought to resolve the confusion:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-misquoted-examples-in-def-var-const-1.patch --]
[-- Type: text/x-patch, Size: 1385 bytes --]

From 8fbe8fa10355845f759b3d8abbb1894f31b46eed Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Thu, 6 Oct 2022 20:41:51 +0200
Subject: [PATCH] Fix misquoted examples in def{var,const}-1

* src/eval.c (Fdefvar_1): Quote the SYM, not the INITVAL.
(Fdefconst_1): Quote the SYM, not the INITVAL.
---
 src/eval.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/eval.c b/src/eval.c
index 8810136c04..56c5c7ea06 100644
--- a/src/eval.c
+++ b/src/eval.c
@@ -834,7 +834,7 @@ DEFUN ("defvar", Fdefvar, Sdefvar, 1, UNEVALLED, 0,
 
 DEFUN ("defvar-1", Fdefvar_1, Sdefvar_1, 2, 3, 0,
        doc: /* Like `defvar' but as a function.
-More specifically behaves like (defvar SYM 'INITVALUE DOCSTRING).  */)
+More specifically behaves like (defvar 'SYM INITVALUE DOCSTRING).  */)
   (Lisp_Object sym, Lisp_Object initvalue, Lisp_Object docstring)
 {
   return defvar (sym, initvalue, docstring, false);
@@ -875,7 +875,7 @@ DEFUN ("defconst", Fdefconst, Sdefconst, 2, UNEVALLED, 0,
 
 DEFUN ("defconst-1", Fdefconst_1, Sdefconst_1, 2, 3, 0,
        doc: /* Like `defconst' but as a function.
-More specifically, behaves like (defconst SYM 'INITVALUE DOCSTRING).  */)
+More specifically, behaves like (defconst 'SYM INITVALUE DOCSTRING).  */)
   (Lisp_Object sym, Lisp_Object initvalue, Lisp_Object docstring)
 {
   CHECK_SYMBOL (sym);
-- 
2.37.3

Re: Typo in defconst-1 and defvar-1 docstrings?

[Philip Kaludercic]

Philip Kaludercic <philipk@posteo.net> writes:

> I was reading through the implementation of defconst-1, but was confused
> by the docstring that states:
>
>    More specifically behaves like (defvar SYM 'INITVALUE DOCSTRING).
>
> Isn't the point of defconst-1 as a functional variant of defconst, that
> SYM will evaluate to a symbol?  And why should INITVALUE be quoted?
> Unless I am mistaken, this patch ought to resolve the confusion:

And related to defconst (which is why I was looking at the definition in
the first place), is there a way to check if a variable was declared
using defconst instead of defvar?

Re: Typo in defconst-1 and defvar-1 docstrings?

[Stefan Monnier]

> I was reading through the implementation of defconst-1, but was confused
> by the docstring that states:
>
>    More specifically behaves like (defvar SYM 'INITVALUE DOCSTRING).
                                     ^^^^^^

It says "defconst" for me (as it should).  Am I missing something?

> Isn't the point of defconst-1 as a functional variant of defconst,

It is.

> that SYM will evaluate to a symbol?

In the function the SYM received is already a symbol.

> And why should INITVALUE be quoted?

Because similarly in the function INITVALUE is really a *value*
(i.e. already evaluated), so in order for `defconst` to behave the same,
you need to quote it to prevent treating that value as an expression
that needs to be evaluated.

E.g. if INITVALUE is the list `(1 2 3)` and SYM is the symbol `hello`,
the equivalent is

    (defconst hello '(1 2 3))

and not

    (defconst 'hello (1 2 3))

which would signal an error because of the quoted symbol and because of
the call to the "function" 1.


        Stefan

Re: Typo in defconst-1 and defvar-1 docstrings?

[Philip Kaludercic]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> I was reading through the implementation of defconst-1, but was confused
>> by the docstring that states:
>>
>>    More specifically behaves like (defvar SYM 'INITVALUE DOCSTRING).
>                                      ^^^^^^
>
> It says "defconst" for me (as it should).  Am I missing something?

I copied the wrong example, my bad.

>> Isn't the point of defconst-1 as a functional variant of defconst,
>
> It is.
>
>> that SYM will evaluate to a symbol?
>
> In the function the SYM received is already a symbol.
>
>> And why should INITVALUE be quoted?
>
> Because similarly in the function INITVALUE is really a *value*
> (i.e. already evaluated), so in order for `defconst` to behave the same,
> you need to quote it to prevent treating that value as an expression
> that needs to be evaluated.
>
> E.g. if INITVALUE is the list `(1 2 3)` and SYM is the symbol `hello`,
> the equivalent is
>
>     (defconst hello '(1 2 3))
>
> and not
>
>     (defconst 'hello (1 2 3))
>
> which would signal an error because of the quoted symbol and because of
> the call to the "function" 1.

OK, I misunderstoond what the comment was trying to say.  Sorry for the
noise.

>         Stefan

Re: Typo in defconst-1 and defvar-1 docstrings?

[Stefan Monnier]

> And related to defconst (which is why I was looking at the definition in
> the first place), is there a way to check if a variable was declared
> using defconst instead of defvar?

Currently, not really, no (beside ugly hacks that only work in some
particular cases, such as trying to jump to the source of the var's
definition and seeing if it says "defvar" or "defconst", or looking at
the `byte-compile-const-variables` var).


        Stefan