Re: variable's documentation string

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