emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Documentation for car and cdr


From: Ken Manheimer
Subject: Re: Documentation for car and cdr
Date: Sun, 29 Jan 2006 16:48:26 -0500

On 1/25/06, Alan Mackenzie <address@hidden> wrote:

> On Wed, 25 Jan 2006, Luc Teirlinck wrote:
>
> >Describing basic concepts like car, cdr, cons cell, list and so on is
> >the task of manuals, not of docstrings.
>
> That has not been established.  And even if it had, a one-liner
> description in a doc-string is likely to be convenient and helpful.
>
> >If somebody is not familiar with the basic concepts, they have to read a
> >manual, where those concepts can be put into the proper context, _not_
> >individual docstrings.
>
> Suppose somebody has read the manuals, a bit.  She knows what car and cdr
> mean, roughly, but isn't quite sure which is which.  C-h f is a
> convenient way of checking.  Or it could be.

i agree.  documentation should be more than precise, it should provide
crucial information about its subject.  as is, the descriptions are
nearly vacuous - someone who knows what the car of a cons is will not
need to read the docstring.  We should be writing the docstring for
those who need to read it, not just the language lawyers.

i can understand being reluctant to fall down a slippery slope, and
wandering beyond the scope of the subject.  it so happens, though,
that car, cdr, and cons constitute a system that can be described very
concisely:

  (car (cons 'x '(a b c))) => 'x
  (cdr (cons 'x '(a b c))) => '(a b c)

Why not indicate the respective example in the docstring for car and
cdr?  I wouldn't suggest including examples in most docstrings,
because most functions either don't need the disambiguation or aren't
as profoundly susceptible to it.

So, eg for car:

  Return the car of a CONS.  For example:

    (car (cons 'x '(a b c)) == 'x

  If arg is nil, return nil.  Error if arg is not nil and not a cons
cell.  See also `car-safe'.

> >There are two different Elisp manuals included with the Emacs
> >distribution.  Why on earth would a beginning Elisp programmer try to
> >learn Elisp exclusively through the docstrings rather than through the
> >one of these two manuals?
>
> Your begging the question here.  I don't think anybody (least of all me)
> is suggesting that doc-strings should supplant the manuals.  But I am
> saying that somebody needing a short snappy one-liner description of a
> function shouldn't be forced to go through the drudgery of opening the
> Elisp manual, finding the page "cdr" is on, then ploughing through all
> the "broadening your horizons" documentation to reach that one critical
> sentence.
>
> Different people use manuals and doc-strings in different ways.

i can't say strongly enough




reply via email to

[Prev in Thread] Current Thread [Next in Thread]