Hmm.

var - Variable: Either a symbol or a cell

(set 'var 'any ..) -> any
    Stores new values any in the var arguments. See also setq, val and def.


Even taken in concert these two snippets don't actually explain what
will happen if var is a cell. It may be obvious (if you already know)
that if var is a cell than action will be taken on the car part.
However it does not actually say so. I note that the definition of con
does say so even though its signature has the more specific data type
of Lst.

The best a very careful first time reader could pick up is that the
behavior is not explicitly spelled out. They could then, guess,
experiment or ask.

I would say that there are some functions where additional verbosity
is warranted. the function for assigning values is one such place.
Especially when the acutal behaviour may not be what people with Lisp
experience expect.

While succinctness is good in documentation, it is possible to have
too much of a good thing.

regs

Konrad.



On 12/10/2008, Alexander Burger <[EMAIL PROTECTED]> wrote:
> Hi Konrad,
>
>> Well thats two improvements to the documentation.
>
> Perhaps a perfect candidate for the Wiki?
>
>
>> The description of set says:
>>
>> Stores new values any in the var arguments. I suspect it should say
>> what you said above.
>
> Well, I wanted to avoid such a verbose description in the references.
>
> 'var' is a special term. Unfortunately, this is only briefly explained,
> in the beginning of the function reference "doc/ref.html#fun". Those
> "primary" and "derived" data types are used excessively throughout the
> documentation, so it would be rather noisy to explain them in every
> function.
>
>
>> and have a see also link to con.
>
> Good point! I added it.
>
> Cheers,
> - Alex
> --
> UNSUBSCRIBE: mailto:[EMAIL PROTECTED]
>
-- 
UNSUBSCRIBE: mailto:[EMAIL PROTECTED]

Reply via email to