variable's documentation string

variable's documentation string

[TheFlyingDutchman]

If I declare a variable:
(defvar myVar 2 "This is the documentation string)

According to the way I read the GNU Emacs Lisp Reference manual I
should be able to retrieve this string with:

(message "the docstring for %s is %s" 'myVar (documentation-property
'myVar 'variable-documentation))

but the output is

the docstring for myVar is nil


Does anyone know what I am missing or doing wrong?

Re: variable's documentation string

[TheFlyingDutchman]

That should be
(defvar myVar 2 "This is the documentation string")  ; typo in the
post only

Re: variable's documentation string

[Pascal J. Bourguignon]

TheFlyingDutchman <zzbbaadd@aol.com> writes:

> That should be
> (defvar myVar 2 "This is the documentation string")  ; typo in the
> post only

Here, it works well:

(defvar myVar 2 "This is the documentation string")     ; C-x C-e
(documentation-property 'myVar 'variable-documentation) ; C-x C-e
--> "This is the documentation string"

Have you evaluated the defvar form?

Was the documentation string present in the first occurence of defvar
for that variable?

(defvar a)                                           
(defvar a "Documentation of A")
(documentation-property 'a 'variable-documentation) 
--> nil

(setf (documentation-property 'a 'variable-documentation) 
       "New documentation of A")
(documentation-property 'a 'variable-documentation) 
--> "New documentation of A"

-- 
__Pascal Bourguignon__

Re: variable's documentation string

[TheFlyingDutchman]

>
> Here, it works well:
>
> (defvar myVar 2 "This is the documentation string")     ; C-x C-e
> (documentation-property 'myVar 'variable-documentation) ; C-x C-e
> --> "This is the documentation string"


Thanks Pascal! You lead me to the error. When I typed (documentation-
property 'some_variable 'variable-documentation) and evaluated it, it
worked. I then compared it to the equivalent part of the message
statement that I was using, and after 15 seconds of looking at it I
realized that I had incorrectly used a dash, instead of an underscore
for the variable name in the documentation-property function call. I
will have to remember to post the exact code I am using and not type
in something equivalent. But I would have expected to have gotten an
error because the symbol-name that I erroneously typed did not exist.
In fact, I would prefer it gave an error to returning nil.

Re: variable's documentation string

[Kevin Rodgers]

TheFlyingDutchman wrote:
>> Here, it works well:
>>
>> (defvar myVar 2 "This is the documentation string")     ; C-x C-e
>> (documentation-property 'myVar 'variable-documentation) ; C-x C-e
>> --> "This is the documentation string"
> 
> 
> Thanks Pascal! You lead me to the error. When I typed (documentation-
> property 'some_variable 'variable-documentation) and evaluated it, it
> worked. I then compared it to the equivalent part of the message
> statement that I was using, and after 15 seconds of looking at it I
> realized that I had incorrectly used a dash, instead of an underscore
> for the variable name in the documentation-property function call. I
> will have to remember to post the exact code I am using and not type
> in something equivalent. But I would have expected to have gotten an
> error because the symbol-name that I erroneously typed did not exist.
> In fact, I would prefer it gave an error to returning nil.

That's not the way Lisp works.  When the form 'some_variable was read,
the symbol was created (with a void value, void function, and nil
property list).

If you evaluate (symbol-value 'some_variable) or (symbol-function
'some_variable), you'll get an error.  But not (symbol-plist
'some_variable).

-- 
Kevin Rodgers
Denver, Colorado, USA

Re: variable's documentation string

[Pascal J. Bourguignon]

TheFlyingDutchman <zzbbaadd@aol.com> writes:

>>
>> Here, it works well:
>>
>> (defvar myVar 2 "This is the documentation string")     ; C-x C-e
>> (documentation-property 'myVar 'variable-documentation) ; C-x C-e
>> --> "This is the documentation string"
>
>
> Thanks Pascal! You lead me to the error. When I typed (documentation-
> property 'some_variable 'variable-documentation) and evaluated it, it
> worked. I then compared it to the equivalent part of the message
> statement that I was using, and after 15 seconds of looking at it I
> realized that I had incorrectly used a dash, instead of an underscore
> for the variable name in the documentation-property function call. I
> will have to remember to post the exact code I am using and not type
> in something equivalent. But I would have expected to have gotten an
> error because the symbol-name that I erroneously typed did not exist.
> In fact, I would prefer it gave an error to returning nil.

In emacs lisp,  variable names are symbols and they all already exist.
The variable documentation is actually stored in the symbol property
list:

(symbol-plist 'myVar)
--> (variable-documentation "This is the documentation string")

(get 'myVar 'variable-documentation) 
--> "This is the documentation string"

and get returns nil when the key doesn't exist:
(get 'myVar 'innexistant-key) 
--> nil

So if you want an error instead of nil, you have to ask it yourself:

(defun variable-documentation (var)
   (or (documentation-property var 'variable-documentation)
       (error "Variable %S has no documentation" var)))

(variable-documentation 'xyz)
==> Debugger entered--Lisp error: (error "Variable xyz has no documentation")

(variable-documentation 'myVar)
--> "This is the documentation string"


-- 
__Pascal Bourguignon__

Re: variable's documentation string

[TheFlyingDutchman]

>
> That's not the way Lisp works.  When the form 'some_variable was read,
> the symbol was created (with a void value, void function, and nil
> property list).
>
> If you evaluate (symbol-value 'some_variable) or (symbol-function
> 'some_variable), you'll get an error.  But not (symbol-plist
> 'some_variable).
>

Thanks Kevin. That certainly is "interesting" behavior. Not what I
would prefer. Is there a way to test that a symbols value and function
are void without getting an error?

Re: variable's documentation string

[TheFlyingDutchman]

>
> So if you want an error instead of nil, you have to ask it yourself:
>
> (defun variable-documentation (var)
>    (or (documentation-property var 'variable-documentation)
>        (error "Variable %S has no documentation" var)))
>
> (variable-documentation 'xyz)
> ==> Debugger entered--Lisp error: (error "Variable xyz has no documentation")
>
> (variable-documentation 'myVar)
> --> "This is the documentation string"
>
> --
> __Pascal Bourguignon__

Thanks Pascal. What I was hoping for was not an error if documentation
is nil, but if the symbol name was invalid. But I guess in Emacs Lisp
there is no such thing as an invalid symbol name. So it would have to
be an error if the symbol was only created from a "read or use", not
from a setq or defvar, etc.

Re: variable's documentation string

[Pascal J. Bourguignon]

TheFlyingDutchman <zzbbaadd@aol.com> writes:

>>
>> That's not the way Lisp works.  When the form 'some_variable was read,
>> the symbol was created (with a void value, void function, and nil
>> property list).
>>
>> If you evaluate (symbol-value 'some_variable) or (symbol-function
>> 'some_variable), you'll get an error.  But not (symbol-plist
>> 'some_variable).
>>
>
> Thanks Kevin. That certainly is "interesting" behavior. Not what I
> would prefer. Is there a way to test that a symbols value and function
> are void without getting an error?

boundp and fboundp.

-- 
__Pascal Bourguignon__

Re: variable's documentation string

[Pascal J. Bourguignon]

TheFlyingDutchman <zzbbaadd@aol.com> writes:

>>
>> So if you want an error instead of nil, you have to ask it yourself:
>>
>> (defun variable-documentation (var)
>>    (or (documentation-property var 'variable-documentation)
>>        (error "Variable %S has no documentation" var)))
>>
>> (variable-documentation 'xyz)
>> ==> Debugger entered--Lisp error: (error "Variable xyz has no documentation")
>>
>> (variable-documentation 'myVar)
>> --> "This is the documentation string"
>>
>> --
>> __Pascal Bourguignon__
>
> Thanks Pascal. What I was hoping for was not an error if documentation
> is nil, but if the symbol name was invalid. But I guess in Emacs Lisp
> there is no such thing as an invalid symbol name. So it would have to
> be an error if the symbol was only created from a "read or use", not
> from a setq or defvar, etc.

Yes, that's the point.  You could test for boundp, but nothing would
prevent you to document variables that are not bound.

Notice that in emacs lisp, you can define a variable without giving it
an initial value:

(defvar *strange*)
(setf (documentation-property '*strange* 'variable-documentation) 
      "A strange variable, with no value")

(boundp '*strange*) 
--> nil

(defun f ()
   (list (boundp '*strange*) 
         (documentation-property '*strange* 'variable-documentation)))

(let ((*strange* 42))
  (f))
--> (t "A strange variable, with no value")

(f)
--> (nil "A strange variable, with no value")


In programs, it is often the case that the best way is to try to do
something and see if there's a problem, rather than trying to see if
doing something could pose a problem.  Foremost because there is no
reliable way to see if doing something could pose a problem, bar doing
it.

Here, if you want the documentation of a variable, the best way is to
try to get it.  And you cannot know when the documentation is not
available, whether it's because the symbol doesn't name a variable of
whether the variable has not been documented.

-- 
__Pascal Bourguignon__