Re: variable's documentation string

[pjb@informatimago.com (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__