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

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

[Alan Mackenzie]

In the master branch in function edebug--backtrace-goto-source there is a
call to function edebug--frame-def-name.  The doc string of the latter
is, in its entirety:

    edebug--frame-def-name is a compiled Lisp function in `edebug.el'.

    (edebug--frame-def-name CL-X)

      This function has a compiler macro `edebug--frame-def-name--cmacro'.
      This function does not change global state, including the match data.

    Access slot "def-name" of `edebug--frame' struct CL-X.

Huh?  Do I really care about whether it has a compiler macro?  I
certainly care about what this function does, and the one liner is
gibberish.  "Access slot "def-name" .... struct CL-X."?  Is "Access" a
verb or an adjective, here?  What on earth is a "def-name"?  What
significance does it have in edebug?  What is the return value of this
function?  All of these points are left open by this alleged doc string.
What does CL-X mean?

It carries on.  If you put point over the `edebug.el' and type <CR>, it
doesn't go to the defining function, throwing an error instead.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

It caries on further, and if anything, gets steadily worse: put point
over `edebug-frame' and hit <CR>.  It leads to another vacuous doc
string.  An `edebug-frame' is a type.  Great!  It is a type of type
cl-structure-class, whatever one of those is.  There follows a columnar
list of something, and some gobbledegook about "Specialized Methods",
whatever they are.  I don't understand it.

At least the link to the source works for `edebug-frame'.  The source
contains NO documentation string, and it is not obvious what an
edebug-frame is or does.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

So, what is a cl-structure-class?  From the most recent doc-string,
follow the link.  We get to another doc string, a profoundly useless one,
which reads

     "cl-structure-class is a type (of kind `cl-structure-class')"

embedded in approximately 26 lines, none of which shed any light on what
a cl-structure-class is, does, or represents.  Following the link just
redisplays the current doc string, ad infinitum.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

Maybe RTFMing will shed light.  Nope: in cl.info, there's not a single
mention of cl-structure-class.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

DOC STRINGS MATTER!!!  Not, perhaps in every last minor private function
in every package, but in obscure cl-* functions used widely throughout
Emacs they most definitely do.

Can we please stop writing code like this?  For everybody but an elite
who likes this sort of thing, it's a massive time sink.  As this sort of
code is steadily proliferated through Emacs, the amount of code readily
maintainable by anybody steadily decreases.  Only this elite can
effectively manage stuff with cl-structure-class in it.  This is not good
for Emacs.

I don't doubt I could, by reading the code, work out what
cl-structure-class does.  But it would be time consuming and dreary, I
would soon forget it again, and I've got plenty of other things to do.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

So, would somebody who likes it please document cl-structure-class and
its friends adequately?

Would somebody please add a doc string, a good one, to `edebug-frame'?

Thanks!

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Drew Adams]

https://lists.gnu.org/archive/html/emacs-devel/2019-07/msg00153.html

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

[Clément Pit-Claudel]

As far as I know, there's no way to provide documentation for a slot of a cl-defstruct.  This sounds like a reasonable feature request (you're looking at an auto-generated docstring).

> I certainly care about what this function does, and the one liner is
> gibberish. "Access slot "def-name" of ‘edebug--frame’ struct CL-X."

Really? You're looking at the documentation of a field accessor — can it be made much better (sort of writing it by hand)?  It's really the same as the following C function, assuming a struct called "backtrace" with a field called "def_name":

  def_name_t backtrace_def_name (backtrace) { return backtrace.def_name }

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

[Stefan Monnier]

>     Access slot "def-name" of `edebug--frame' struct CL-X.
>
> Huh?  Do I really care about whether it has a compiler macro?  I
> certainly care about what this function does, and the one liner is
> gibberish.

Not sure what you mean by gibberish.  The function itself is
a one-liner, all it does is (as the docstring says) is that it accesses
the slot called "def-name" of the struct CL-X which is presumed to be of
type `edebug--frame`.

> What significance does it have in edebug?

The "--" indicates it's an internal function.  These are quit often
not documented.

> What is the return value of this
> function?  All of these points are left open by this alleged doc string.
> What does CL-X mean?

It's the name of the argument, as always.  See the earlier line:

    (edebug--frame-def-name CL-X)

The choice of `CL-X` as argument name is indeed poor.  It should
probably be ARG or V or X instead.  The use of a `cl-` prefix is
a remnant of the time where we didn't have lexical scoping, IIRC.

> It carries on.  If you put point over the `edebug.el' and type <CR>, it
> doesn't go to the defining function, throwing an error instead.

Indeed, that's unfortunate.  We should improve either `cl-defstruct` or
`find-function` to fix this.

> It caries on further, and if anything, gets steadily worse: put point
> over `edebug-frame' and hit <CR>.  It leads to another vacuous doc
> string.

This one can be improved by the patch below (which is the kind of patch
you reject in CC-mode, ironically enough).

> ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> So, what is a cl-structure-class?

You said so yourself: Since `edebug--frame` is a type of type
`cl-structure-class`, then `cl-structure-class` is a "type of types".
IOW a metaclass.

>      "cl-structure-class is a type (of kind `cl-structure-class')"
>
> embedded in approximately 26 lines, none of which shed any light on what
> a cl-structure-class is, does, or represents.

There actual docstring says: "The type of CL structs descriptors."
The rest describes the fields of those CL struct descriptors (aka class
objects).

Since we're in the realm of metaclasses here, it's no wonder that the
info you'll find here won't be very helpful to understand
`edebug--frame-def-name`.

> Following the link just redisplays the current doc string,
> ad infinitum.

Indeed, this metaclass is its own metaclass (that's the usual way to
stop the recursion).


        Stefan


diff --git a/lisp/emacs-lisp/edebug.el b/lisp/emacs-lisp/edebug.el
index a376067443a..1b4bbb54e59 100644
--- a/lisp/emacs-lisp/edebug.el
+++ b/lisp/emacs-lisp/edebug.el
@@ -4169,12 +4169,12 @@ edebug-instrumented-backtrace-frames
   "Stack frames of the current Edebug Backtrace buffer with instrumentation.
 This should be a list of `edebug---frame' objects.")
 
-;; Data structure for backtrace frames with information
-;; from Edebug instrumentation found in the backtrace.
 (cl-defstruct
     (edebug--frame
      (:constructor edebug--make-frame)
      (:include backtrace-frame))
+  "Data structure for backtrace frames with information
+from Edebug instrumentation found in the backtrace."
   def-name before-index after-index)
 
 (defun edebug-pop-to-backtrace ()

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

[Alan Mackenzie]

Hello, Clément.

On Tue, May 05, 2020 at 17:11:43 -0400, Clément Pit-Claudel wrote:
> As far as I know, there's no way to provide documentation for a slot
> of a cl-defstruct.  This sounds like a reasonable feature request
> (you're looking at an auto-generated docstring).

> > I certainly care about what this function does, and the one liner is
> > gibberish. "Access slot "def-name" of ‘edebug--frame’ struct CL-X."

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

And why such a woolly, meaningless word like "access"?  Are we talking
about a read access or a write access here?  It's a bit like writing in
a doc string "_consider_ the input value" - vague and unhelpful, and
calculated to get people writing angry rants on emacs-devel..

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?

And like you say above, even that much is only a little bit helpful when
the main thing needing documenting is the return value of the function
call - what precisely a def-name is.  After all, in the doc string for
parse-partial-sexp, we don't just say it returns an 11-element list.

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.

> It's really the same as the following C function, assuming a struct
> called "backtrace" with a field called "def_name":

>   def_name_t backtrace_def_name (backtrace) { return backtrace.def_name }

If the vagueness were fixed, so that that doc string was self-contained
and informative, I would be happy about it.

-- 
Alan Mackenzie (Nuremberg, Germany).

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

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

[Stefan Monnier]

> And like you say above, even that much is only a little bit helpful when
> the main thing needing documenting is the return value of the function
> call - what precisely a def-name is.

The function has no idea what that is.

> After all, in the doc string for parse-partial-sexp, we don't just say
> it returns an 11-element list.

That's a bad analogy: the 11-element list is completely constructed by
`parse-partial-sexp` so it knows very precisely what's in there.

In contrast Edebug's slot-accessor only knows that it returns the
content of that slot.  So it's more like `cl-third` or `nth` which can't
tell you much about their return value other than where it comes from.

This can be addressed by adding a `:documentation` to the slot in
`edebug.el`, tho.  But, for that you'll first need to find someone who
knows/understands that code.  Maybe you'll be the one best placed to add
that doc after you solve the problem that lead you to look at that
function ;-)


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Wed, 06 May 2020 14:20:15 -0400
> Cc: Clément Pit-Claudel <cpitclaudel@gmail.com>,
>  emacs-devel@gnu.org
> 
> -                       ,(format "Access slot \"%s\" of `%s' struct CL-X.%s"
> +                       ,(format "Return value of the slot \"%s\" of `%s' struct CL-X.%s"

"Return (the) value" sounds like it's a read-only access.

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

[Alan Mackenzie]

Hello, Stefan.

Sorry it's been a long time since your post.  Some of my repo copies got
corrupted, and sorting them out was a priority.  I managed it, thanks to
my back up copies.

On Tue, May 05, 2020 at 18:18:26 -0400, Stefan Monnier wrote:
> >     Access slot "def-name" of `edebug--frame' struct CL-X.

> > Huh?  Do I really care about whether it has a compiler macro?  I
> > certainly care about what this function does, and the one liner is
> > gibberish.

> Not sure what you mean by gibberish.

That it's meaning is clear only to those who already know it.

> The function itself is a one-liner, all it does is (as the docstring
> says) is that it accesses the slot called "def-name" of the struct
> CL-X which is presumed to be of type `edebug--frame`.

No, that is not what it does.  It GETs the value in that slot and
RETURNS IT.  That last is the critical thing.  Your sentence,
containing as it does verbs and articles, is clear.  The contents of the
doc string is anything but.

> > What significance does it have in edebug?

> The "--" indicates it's an internal function.  These are quite often
> not documented.

Or they are documented by comments.  An otherwise obscure object
requires one or the other.  Here it has neither.

> > What is the return value of this function?  All of these points are
> > left open by this alleged doc string.  What does CL-X mean?

> It's the name of the argument, as always.

A typical useful doc string would give information about the semantics
of the argument, saying, say,  "where CL-X is a list".

> See the earlier line:

>     (edebug--frame-def-name CL-X)

> The choice of `CL-X` as argument name is indeed poor.  It should
> probably be ARG or V or X instead.  The use of a `cl-` prefix is
> a remnant of the time where we didn't have lexical scoping, IIRC.

> > It carries on.  If you put point over the `edebug.el' and type <CR>, it
> > doesn't go to the defining function, throwing an error instead.

> Indeed, that's unfortunate.  We should improve either `cl-defstruct` or
> `find-function` to fix this.

Thanks, I agree with that.

> > It caries on further, and if anything, gets steadily worse: put point
> > over `edebug-frame' and hit <CR>.  It leads to another vacuous doc
> > string.

> This one can be improved by the patch below (which is the kind of patch
> you reject in CC-mode, ironically enough).

> > ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> > So, what is a cl-structure-class?

> You said so yourself: Since `edebug--frame` is a type of type
> `cl-structure-class`, then `cl-structure-class` is a "type of types".
> IOW a metaclass.

If I said, to a normal person, "a foo is a baz of a baz" they would be
left none the wiser, and might retort "but what IS a foo?".  That's
where I was at the beginning of the week.  I don't know what a
"metaclass" is, I'm still not sure what a cl-structure-class is and the
latter needs documenting coherently.

> >      "cl-structure-class is a type (of kind `cl-structure-class')"

> > embedded in approximately 26 lines, none of which shed any light on what
> > a cl-structure-class is, does, or represents.

> There actual docstring says: "The type of CL structs descriptors."
> The rest describes the fields of those CL struct descriptors (aka class
> objects).

It most assuredly does not.  It _lists_ those fields - it does not
describe them.  One of these fields, for example, is called named.  What
does named do?  What does it represent?  What's it for?  None of these
questions is answered.  named is undocumented, as are all the other
fields.  Why?

> Since we're in the realm of metaclasses here, it's no wonder that the
> info you'll find here won't be very helpful to understand
> `edebug--frame-def-name`.

> > Following the link just redisplays the current doc string,
> > ad infinitum.

> Indeed, this metaclass is its own metaclass (that's the usual way to
> stop the recursion).

A better way would be actually to document it.  It consists of a lot of
fields.  Each of them need documenting for this doc string to be useful,
together with some explanation of what "CL structs descriptors" are.

On the whole, the semantics of Emacs is described in its doc strings.
In that for cl-structure-class, and probably most of its friends, only
syntax is described.  That is a Bad Thing.

>         Stefan


> diff --git a/lisp/emacs-lisp/edebug.el b/lisp/emacs-lisp/edebug.el
> index a376067443a..1b4bbb54e59 100644
> --- a/lisp/emacs-lisp/edebug.el
> +++ b/lisp/emacs-lisp/edebug.el
> @@ -4169,12 +4169,12 @@ edebug-instrumented-backtrace-frames
>    "Stack frames of the current Edebug Backtrace buffer with instrumentation.
>  This should be a list of `edebug---frame' objects.")
 
> -;; Data structure for backtrace frames with information
> -;; from Edebug instrumentation found in the backtrace.
>  (cl-defstruct
>      (edebug--frame
>       (:constructor edebug--make-frame)
>       (:include backtrace-frame))
> +  "Data structure for backtrace frames with information
> +from Edebug instrumentation found in the backtrace."
>    def-name before-index after-index)
 
>  (defun edebug-pop-to-backtrace ()

That just moves text from a comment to a doc string.  It doesn't help
find out what edebug--frame-def-name does.

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Alan Mackenzie]

Hello, Stefan.

On Wed, May 06, 2020 at 14:20:15 -0400, Stefan Monnier wrote:

[ .... ]

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

Quite the opposite.  :-)  Please commit it.

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

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[Stefan Monnier]

>> >     Access slot "def-name" of `edebug--frame' struct CL-X.
[...]
>> It's the name of the argument, as always.
> A typical useful doc string would give information about the semantics
> of the argument, saying, say,  "where CL-X is a list".

Hmm... but it does: it says that it's an "`edebug--frame' struct".

> where I was at the beginning of the week.  I don't know what a
> "metaclass" is,

It's a generic term from the OO crowd.  It's class of a class: in
languages where classes can be manipulated as normal objects, they
themselves belong to a class, called the metaclass (which is hence
itself a class with its own metaclass, etc...).

Luckily you shouldn't need to know any of those things unless you need
to dig into the implementation of Elisp's OO facilities such as
`cl-defstruct`, `eieio`, or `cl-generic`, basically.

> I'm still not sure what a cl-structure-class is and the
> latter needs documenting coherently.

I guess it would be good, yes.  In the mean time, just like for a lot of
the CL stuff you can start by looking it up in the HyperSpec:
http://www.lispworks.com/documentation/HyperSpec/Body/t_stu_cl.htm#structure-class

>> >      "cl-structure-class is a type (of kind `cl-structure-class')"
>
>> > embedded in approximately 26 lines, none of which shed any light on what
>> > a cl-structure-class is, does, or represents.
>
>> There actual docstring says: "The type of CL structs descriptors."
>> The rest describes the fields of those CL struct descriptors (aka class
>> objects).
>
> It most assuredly does not.  It _lists_ those fields - it does not
> describe them.  One of these fields, for example, is called named.  What
> does named do?  What does it represent?  What's it for?  None of these
> questions is answered.  named is undocumented, as are all the other
> fields.  Why?

Why do you need to know?

This class is used by `cl-defstruct` and pretty much nothing else, so
presumably if you need to know about it you're hacking on
`cl-defstruct`, and if you're hacking on `cl-defstruct` the first thing
to do is to look up its documentation (unless you know it already,
obviously).  After that it should be trivial to guess what this `named`
field is used for.

In your case, you're investigating `edebug--frame`, which should not
depend on the way `cl-defstruct` is implemented.  Kind of like looking
at the "vtables" generated by your C++ compiler.

> A better way would be actually to document it.

Be my guest.


        Stefan

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

[Eli Zaretskii]

> Date: Fri, 8 May 2020 19:59:08 +0000
> From: Alan Mackenzie <acm@muc.de>
> Cc: Clément Pit-Claudel <cpitclaudel@gmail.com>,
>  emacs-devel@gnu.org
> 
> > Any objection to the patch below?
> 
> Quite the opposite.  :-)  Please commit it.

Once again: "Return value" doesn't sound right to me, since it implies
read-only access to the value, something that AFAIU is inaccurate.  It
actually returns a settable "place", doesn't it?

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

[Stefan Monnier]

> Once again: "Return value" doesn't sound right to me, since it implies
> read-only access to the value, something that AFAIU is inaccurate.  It
> actually returns a settable "place", doesn't it?

AFAIK the official name for that in OO parlance is an "accessor".
Which is why I used the verb "Access".


        Stefan

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Alan Mackenzie <acm@muc.de>,  cpitclaudel@gmail.com,  emacs-devel@gnu.org
> Date: Sat, 09 May 2020 09:47:03 -0400
> 
> > Once again: "Return value" doesn't sound right to me, since it implies
> > read-only access to the value, something that AFAIU is inaccurate.  It
> > actually returns a settable "place", doesn't it?
> 
> AFAIK the official name for that in OO parlance is an "accessor".
> Which is why I used the verb "Access".

That's okay, but the patch in question proposes to replace "Access"
with "Return value of", and I think this will make the documentation
less accurate than the original.  Or am I missing something?

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

[Alan Mackenzie]

Hello, Eli.

On Sat, May 09, 2020 at 08:53:14 +0300, Eli Zaretskii wrote:
> > Date: Fri, 8 May 2020 19:59:08 +0000
> > From: Alan Mackenzie <acm@muc.de>
> > Cc: Clément Pit-Claudel <cpitclaudel@gmail.com>,
> >  emacs-devel@gnu.org

> > > Any objection to the patch below?

> > Quite the opposite.  :-)  Please commit it.

> Once again: "Return value" doesn't sound right to me, since it implies
> read-only access to the value, something that AFAIU is inaccurate.  It
> actually returns a settable "place", doesn't it?

I don't know precisely what a "place" is.  I think it just means
"a form you can use setf on".  I read about it in the Elisp manual this
afternoon, but didn't get a strong impression from that.  I don't think
you can talk about a "place" as though it were a value.

So "(car foo)" (the form) could be considered a "place", since you can
use setf on it.  However that "place" is not the return value of
evaluating that form.  Or something like that.  I find it confusing.

The point about the documentation in question is that it currently
doesn't define what a function returns, and "to access" something, on
its own, is frustratingly vague.  it is on a par with defining zerop as
"Compare a number.".

So, I think the doc string in question _needs_ to use the phrase "return
value", and I think it is an accurate description of the result of
(read) "accessing" the slot.

-- 
Alan Mackenzie (Nuremberg, Germany).

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

[tomas]

[-- Attachment #1: Type: text/plain, Size: 538 bytes --]

On Sat, May 09, 2020 at 02:56:19PM +0000, Alan Mackenzie wrote:

[...]

> I don't know precisely what a "place" is [...]

I think the best metaphor (it's metaphors all the way down, isn't it)
is an "lvalue". Something you can assign to (but if you use the same
"thing" whithin an expression, you get its value). Thing is, in C
an lvalue isn't a first-order object [1], you can't push it around.
Lisp, OTOH...

Cheers
[1] Well, it isn't really a first order object in Lisp either,
   but your code can pretend, up to a certain point.
-- t

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

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

[Eli Zaretskii]

> Date: Sat, 9 May 2020 14:56:19 +0000
> Cc: monnier@iro.umontreal.ca, cpitclaudel@gmail.com, emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> > Once again: "Return value" doesn't sound right to me, since it implies
> > read-only access to the value, something that AFAIU is inaccurate.  It
> > actually returns a settable "place", doesn't it?
> 
> I don't know precisely what a "place" is.  I think it just means
> "a form you can use setf on".

Yes,l among other things.  See "Generalized Variables" in the ELisp
manual.

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

[Andreas Schwab]

On Mai 09 2020, tomas@tuxteam.de wrote:

> On Sat, May 09, 2020 at 02:56:19PM +0000, Alan Mackenzie wrote:
>
> [...]
>
>> I don't know precisely what a "place" is [...]
>
> I think the best metaphor (it's metaphors all the way down, isn't it)
> is an "lvalue".

Or like a reference in C++.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

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

[Madhu]

* Stefan Monnier <jwv7dxmtckj.fsf-monnier+emacs@gnu.org> :
Wrote on Fri, 08 May 2020 16:24:28 -0400:

>> where I was at the beginning of the week.  I don't know what a
>> "metaclass" is,
>
> It's a generic term from the OO crowd.  It's class of a class: in
> languages where classes can be manipulated as normal objects, they
> themselves belong to a class, called the metaclass (which is hence
> itself a class with its own metaclass, etc...).
>
> Luckily you shouldn't need to know any of those things unless you need
> to dig into the implementation of Elisp's OO facilities such as
> `cl-defstruct`, `eieio`, or `cl-generic`, basically.

Unfortunately we need to know because we have to deal with your
misdesign of those features and language constructs.  While the concepts
are ostensibky taken from common lisp the implementation shares none of
the spirit of lisp which makes it impossible to work with.

Redefinitions of cl-generics are not possible. I have repeatedly come
across code that uses these features you have introduced, which get into
debug situations where emacs cannot be debugged but needs be killed.

I have  cases (related  debbug) when edbug is essentially unusable and
worse it is so *by your design*. These are not problems that are fixable
without fixing your implementation.
>
>> I'm still not sure what a cl-structure-class is and the
>> latter needs documenting coherently.
>
> I guess it would be good, yes.  In the mean time, just like for a lot of
> the CL stuff you can start by looking it up in the HyperSpec:
> http://www.lispworks.com/documentation/HyperSpec/Body/t_stu_cl.htm#structure-class

Again these do not help deal with your perverse idiosyncratic "write
only" implementations which implement your particular nauseous flavour
and opinion of the language which is now forced on elisp.

There isnt any way to submit patches to your code.

The elisp code base has been irrecoverably subverted by your
contributions and there is no way to go back to the pleasurable
debugging-eden which emacs was before you started "contributing"
>
>>> >      "cl-structure-class is a type (of kind `cl-structure-class')"
>>
>>> > embedded in approximately 26 lines, none of which shed any light on what
>>> > a cl-structure-class is, does, or represents.
>>
>>> There actual docstring says: "The type of CL structs descriptors."
>>> The rest describes the fields of those CL struct descriptors (aka class
>>> objects).
>>
>> It most assuredly does not.  It _lists_ those fields - it does not
>> describe them.  One of these fields, for example, is called named.  What
>> does named do?  What does it represent?  What's it for?  None of these
>> questions is answered.  named is undocumented, as are all the other
>> fields.  Why?
>
> Why do you need to know?

In order to deal with mishbehaving code which uses the features and code
which you have authored.

It is no longer the case that understanding the principles of lisp is
enough to deal with emacs lisp.  Every particular twist in thinking that
you have painfully gone through and opaquely introduced into the code
base has to be unravelled and worked around before a piece of code can
be understood and debugged.


> This class is used by `cl-defstruct` and pretty much nothing else, so
> presumably if you need to know about it you're hacking on
> `cl-defstruct`, and if you're hacking on `cl-defstruct` the first thing
> to do is to look up its documentation (unless you know it already,
> obviously).  After that it should be trivial to guess what this `named`
> field is used for.
>
> In your case, you're investigating `edebug--frame`, which should not
> depend on the way `cl-defstruct` is implemented.  Kind of like looking
> at the "vtables" generated by your C++ compiler.

Like vtables the intent again is code obfuscation  -  and the lead up to
the its "open source you have the code" taunt


>> A better way would be actually to document it.
>
> Be my guest.

Another taunt - which seems to be the basic motivation for your
"contributions" to emacs.

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

[Eli Zaretskii]

On May 12, 2020 9:33:49 AM GMT+03:00, Madhu <enometh@meer.net> wrote:
> * Stefan Monnier <jwv7dxmtckj.fsf-monnier+emacs@gnu.org> :
> Wrote on Fri, 08 May 2020 16:24:28 -0400:
> 
> >> where I was at the beginning of the week.  I don't know what a
> >> "metaclass" is,
> >
> > It's a generic term from the OO crowd.  It's class of a class: in
> > languages where classes can be manipulated as normal objects, they
> > themselves belong to a class, called the metaclass (which is hence
> > itself a class with its own metaclass, etc...).
> >
> > Luckily you shouldn't need to know any of those things unless you
> need
> > to dig into the implementation of Elisp's OO facilities such as
> > `cl-defstruct`, `eieio`, or `cl-generic`, basically.
> 
> Unfortunately we need to know because we have to deal with your
> misdesign of those features and language constructs.

[More toxic language elided.]

Please tone down your messages.  Regardless of whether one agrees with your technical arguments (I don't, FTR), the tone and toxic accusations are unacceptable.  Please be sure not to accuse anyone here of being incompetent, and Stefan less than anyone else.

cl-generic misdesign (was: Poor quality documentation in edebug.el, and recursive documentation)

[Stefan Monnier]

Hi Madhu,

> Unfortunately we need to know because we have to deal with your
> misdesign of those features and language constructs.

Always looking forward to your kind words.

> Redefinitions of cl-generics are not possible.

I wouldn't be surprised if there are problems in this area, indeed, but
"not possible" doesn't match my experience:

    ELISP> (cl-defgeneric sm-foo (a))
    :autoload-end
    ELISP> (cl-defmethod sm-foo ((a (eql 1))) 2)
    sm-foo
    ELISP> (sm-foo 1)
    2 (#o2, #x2, ?\C-b)
    ELISP> (cl-defmethod sm-foo ((a (eql 1))) 3)
    sm-foo
    ELISP> (sm-foo 1)
    3 (#o3, #x3, ?\C-c)
    ELISP>

> I have repeatedly come across code that uses these features you have
> introduced, which get into debug situations where emacs cannot be
> debugged but needs be killed.

Sounds like a bug or a misfeature, indeed.

> I have cases (related debbug) when edbug is essentially unusable and
> worse it is so *by your design*.

I don't know what you're referring to.  Could you point to those debbugs?

> There isnt any way to submit patches to your code.

I don't think cl-generic.el is more magical than the rest of Emacs, so
`M-x report-emacs-bug` should work to submit patches.  At least I can't
see how `M-x report-emacs-bug` could fail to submit a patch just because
it's about cl-generic.el.


        Stefan

Re: cl-generic misdesign (was: Poor quality documentation in edebug.el, and recursive documentation)

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > > Unfortunately we need to know because we have to deal with your
  > > misdesign of those features and language constructs.

I am sorry he said that to you.  Those words were uncalled-for.

None of us is perfect, and none of us has time to consider every
contingency.  So every program we write has shortcomings (and bugs,
too).  If people use the program a lot, they will use it in ways we
did not imagine, and sometimes it won't handle them well.

C'est la programmation.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)