Re: Poor quality documentation in edebug.el, and recursive documentation.

[Stefan Monnier]

>> Really? You're looking at the documentation of a field accessor — can
>> it be made much better (sort of writing it by hand)?
> It could be made much better.  For a start, it shouldn't be
> syntactically ambiguous - It could be talking about "an access slot" or
> "accessing the slot".  I think you're telling me that the second is
> meant.

I'm not sure what that would look like in practice.  I may be to blame
for the current wording and I'm definitely not wedded to it, so I'd
welcome concrete suggestions.

For the record, part of the motivation for the current wording is that
traditionally the first line of the docstring of a function describes
concisely what the function *does* in the present/imperative tense.
So "an access slot" or "accessing the slot" would be quite unusual.

I don't have strong feelings about whether such unusual would be good or
not, but I think other people might.

> And why such a woolly, meaningless word like "access"?  Are we talking
> about a read access or a write access here?

Actually it works for both since it's a "place" (i.e. it works with
`setf`, `push`, ...).

> Now people have explained it, I see that it means "return the value of
> the slot def-name".  That is explicit and says what is done.
> Why can that not be written?

Sounds fine to me, yes.

Any objection to the patch below?

> And why is the edebug--frame's metasyntactic variable called CL-X?  If
> somebody were trying deliberately to be unhelpful, that is what they
> would call it.

I answered this in an earlier message, which I assume you've read since.


        Stefan


diff --git a/lisp/emacs-lisp/cl-macs.el b/lisp/emacs-lisp/cl-macs.el
index 4408bb58464..237d85b81d3 100644
--- a/lisp/emacs-lisp/cl-macs.el
+++ b/lisp/emacs-lisp/cl-macs.el
@@ -2899,7 +2899,7 @@ cl-defstruct
              ;; The arg "cl-x" is referenced by name in eg pred-form
              ;; and pred-check, so changing it is not straightforward.
              (push `(,defsym ,accessor (cl-x)
-                       ,(format "Access slot \"%s\" of `%s' struct CL-X.%s"
+                       ,(format "Return value of the slot \"%s\" of `%s' 
struct CL-X.%s"
                                 slot name
                                 (if doc (concat "\n" doc) ""))
                        (declare (side-effect-free t))