bug#14278: 24.3.50; doc of `defstruct'

[Lars Ingebrigtsen <larsi@gnus.org>]

"Drew Adams" <drew.adams@oracle.com> writes:

> The doc string says "Each SLOT may instead..." - instead of what?  It
> forgets to say that a slot can be a symbol.

Now fixed.

"Drew Adams" <drew.adams@oracle.com> writes:

> 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.

This was already fixed.

> 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.

This was fixed in 2019.

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

I think that's clear enough.

> 4. The doc string does not say that NAME can be a symbol.

Fixed now.

> 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).

Ditto.

> 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.

Already fixed.

> 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.

I think this is clear enough as is.

"Drew Adams" <drew.adams@oracle.com> writes:

> 6. The manual says "(The SLOTS may begin with a string which documents the
> structure type.)".  The doc string says nothing about this.

Fixed now.

> 7. Does this mean that SLOTS can begin with a string or each element of SLOTS
> (each slot) can begin with a string?  (Another problem with trying to make
> "SLOTS" do double-duty in the doc. 

Clarified.

> 9. The doc should say, if it is true (as in Common Lisp), that no part of the
> defstruct options is evaluated (unlike the case for SLOTS).

I don't think that there's any confusion possible here.

"Drew Adams" <drew.adams@oracle.com> writes:

> 10. It is not a good idea to use as the illustrative example one that has a slot
> named "name".  So much possible confusion with parameter NAME, etc.
>
>  In the simplest case, NAME and each of the SLOTS are symbols.
>                        ^^^^
>  For example,
>
>   (cl-defstruct person name age sex)
>                        ^^^^

True; I've adjusted the examples now.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no