Re: Documentation for car and cdr

[Ken Manheimer]

On 1/29/06, Ken Manheimer <address@hidden> wrote:
> 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

[crap - my hand slipped, and some keybinding sent the mail before i was done]

i can't say strongly enough that you need to consider who is seeking
information from the docstring when writing the docstring.  language
lawyers know what `car' does - you need to ask what clues will help
someone who is lost enough to ask.  telling them that it returns the
car will seem callous, particularly when there is one small piece of
salient information - that the car is the leading element - which the
docstring can provide.

ken
address@hidden