bug#14278: 24.3.50; doc of `defstruct'

bug#14278: 24.3.50; doc of `defstruct'

[Drew Adams]

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.
 
 
 
In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-04-17 on ODIEONE
Bzr revision: 112320 monnier@iro.umontreal.ca-20130418001233-g6wsqi5bpq2hsd0k
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'
 

bug#14278: 24.3.50; doc of `defstruct'

[Drew Adams]

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

bug#14278: 24.3.50; doc of `defstruct'

[Drew Adams]

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

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. 

8. And in either case, how does such a string "document the structure type"?
(Is it instead perhaps a part of NAME and not SLOTS?)

I see nothing in the Common Lisp defstruct that resembles such a "string which
documents the structure type".  Searching the relevant sections of CLTL2E for
"doc" and "string" turns up nothing in this regard.

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

bug#14278: 24.3.50; doc of `defstruct'

[Drew Adams]

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

bug#14278: 24.3.50; doc of `defstruct'

[Lars Ingebrigtsen]

"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