Re: emacs-29 a5bd9fb8c4a: ; Improve doc strings in register.el

[Michael Heerdegen]

Eli Zaretskii <eliz@gnu.org> writes:

> > From: Michael Heerdegen <michael_heerdegen@web.de>
> > Cc: Eli Zaretskii <eliz@gnu.org>
> > Date: Sun, 02 Jul 2023 04:28:10 +0200
> >
> > >  (cl-defgeneric register-val-describe (val verbose)
> > > -  "Print description of register value VAL to `standard-output'."
> > > +  "Print description of register value VAL to `standard-output'.
> > > +Second argument VERBOSE is ignored, unless VAL is not one of the
> > > +supported kinds of register contents, in which case it is displayed
> > > +using `prin1'."
> > >    (princ "Garbage:\n")
> > >    (if verbose (prin1 val)))
> >
> > I would remove that sentence you added: the body is only the generic
> > (fallback) definition; method implementations are free to use the
> > VERBOSE argument (some actually do).
>
> I see no need to remove it.  I added it on purpose: a mandatory
> argument deserves to be documented, and the fact that it's a generic
> doesn't matter because the doc string should describe all the concrete
> methods.

Sure.  IMO the optimum would be to describe first what the generic
function generally does (the common part of all implementations, what
the arguments mean, etc.)  and then (optionally) describe the default
implementation but in a way that says that explicitly ("The default
implementation ...").  I also wondered why you had described the `princ'
behavior but not the (also interesting) "Garbage: " part.

>  But I changed it to be more in line with its usage by the
> methods which do use this argument.

Thanks, I think that's better.

Michael.