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

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

[Michael Heerdegen]

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

Hello Eli,

thanks for improving the documentation of registers and text property
search.  All fine, only:

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

And here are two typos (please install if it looks ok):


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Fix-two-typos-in-recent-changes-in-the-manual.patch --]
[-- Type: text/x-diff, Size: 1737 bytes --]

From b426979d46f4823b3ddd850902a73aff970b5a24 Mon Sep 17 00:00:00 2001
From: Michael Heerdegen <michael_heerdegen@web.de>
Date: Sun, 2 Jul 2023 03:35:34 +0200
Subject: [PATCH] ; Fix two typos in recent changes in the manual

* doc/lispref/text.texi (Property Search):
* lisp/register.el (register-preview-function): Fix typos.
---
 doc/lispref/text.texi | 2 +-
 lisp/register.el      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index a61889fc508..bfd81662292 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -3424,7 +3424,7 @@ Property Search
 region where we have a property match, skip past that region and find
 the next region instead.

-The @code{prop-match} structure has the following accessor functionss:
+The @code{prop-match} structure has the following accessor functions:
 @code{prop-match-beginning} (the start of the match),
 @code{prop-match-end} (the end of the match), and
 @code{prop-match-value} (the value of @var{property} at the start of
diff --git a/lisp/register.el b/lisp/register.el
index 56ab089efb7..06a52a3850e 100644
--- a/lisp/register.el
+++ b/lisp/register.el
@@ -126,7 +126,7 @@ register-preview-default
 (defvar register-preview-function #'register-preview-default
   "Function to format a register for previewing.
 Called with one argument, a cons (NAME . CONTENTS) as found in `register-alist'.
-The function should return a string, the description of teh argument.")
+The function should return a string, the description of the argument.")

 (defun register-preview (buffer &optional show-empty)
   "Pop up a window showing the registers preview in BUFFER.
--
2.30.2


[-- Attachment #3: Type: text/plain, Size: 20 bytes --]



Thanks,

Michael.

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

[Eli Zaretskii]

> 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.  But I changed it to be more in line with its usage by the
methods which do use this argument.

> And here are two typos (please install if it looks ok):

Thanks, installed.

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.