[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#14278: 24.3.50; doc of `defstruct'
From: |
Lars Ingebrigtsen |
Subject: |
bug#14278: 24.3.50; doc of `defstruct' |
Date: |
Sat, 21 Aug 2021 16:50:24 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) |
"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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- bug#14278: 24.3.50; doc of `defstruct',
Lars Ingebrigtsen <=