bug#14278: 24.3.50; doc of `defstruct'

["Drew Adams" <drew.adams@oracle.com>]

> Both the doc string and (cl) `Structures' are a bit sloppy in their
> descriptions.  SLOTS is the name of one parameter.  It is incorrect to
> speak of SLOT unless that has been defined as one of the elements of
> list SLOTS.  And it needs in fact to be said that SLOTS is a list.
>  
> The doc string says "Each SLOT may instead..." - instead of what?  It
> forgets to say that a slot can be a symbol.

Things are worse than that, in fact.

1. The manual says that each element of SLOT, if not a symbol, is a list
(SLOT-NAME DEFAULT-VALUE SLOT-OPTIONS...).  But the doc string says it is (SLOT
SLOT-OPTS...), forgetting DEFAULT-VALUE altogether.

2. The manual does not say what each element of SLOT-OPTIONS is.  The doc string
at least says that SLOT-OPTS is a list of key value pairs.  Both manual and doc
string would be better off saying that SLOT-OPT[ION]S is a plist, and describe
what the keys and values of the plist can be.

3. The same problems reported originally for SLOTS exist also for NAME.  It
speaks of OPTION without giving that term any relation to OPTIONS.

4. The doc string does not say that NAME can be a symbol.  The manual says that
NAME can be a list of a symbol followed by "struct options" (it should
presumably say "structure options", since that is the term used elsewhere in the
node).

But the manual does not say that a structure option here is either a KEYWORD or
a pair (KEYWORD VALUE).  In this case the doc string is more complete (assuming
it is correct here) - the manual provides no help with this.

5. It is misleading and confusing to write "NAME may instead take the form (NAME
OPTIONS...)".  That sounds like a recursive definition, allowing for, say, NAME
to be (foo (foo (foo ...) bar))).  Use two different names: NAME and NAME1 or
something, else it is impossible to know when you are referring to the parameter
and when you are referring to one of its parts.