From: Matt <matt@excalamus.com>
To: "Andreas Schwab" <schwab@suse.de>
Cc: 69745 <69745@debbugs.gnu.org>
Subject: bug#69745: [PATCH] Fix incorrect Edebug docstrings
Date: Fri, 15 Mar 2024 18:22:55 +0100 [thread overview]
Message-ID: <18e43236053.ea8d2a62434521.1358079795129399231@excalamus.com> (raw)
In-Reply-To: <mvmh6hbobap.fsf@suse.de>
[-- Attachment #1: Type: text/plain, Size: 2112 bytes --]
---- On Tue, 12 Mar 2024 13:59:58 +0100 Andreas Schwab wrote ---
> On Mär 12 2024, Matt wrote:
>
> > When edebug-print-length and edebug-print-level are nil, they default to print-level and print-length. The docstrings currently say the opposite, that edebug defaults to the print variables if non-nil.
>
> That's not correct. The edebug-print-* variables, when non-nil,
> override the corresponding print-* variables during printing (see
> edebug-safe-prin1-to-string). When they are nil, they have no effect.
>
> > (defcustom edebug-print-length 50
> > - "If non-nil, default value of `print-length' for printing results in Edebug."
> > + "If nil, default value of `print-length' is used for printing results in Edebug."
>
> That fails to say what happens if it is non-nil, which is the actual
> relevant information.
Thanks for taking the time to review this.
You are correct in the functioning. The problem is the current docstrings are ambiguous. Consider the current description for 'edebug-print-length':
"If non-nil, default value of ‘print-length’ for printing results in Edebug."
This has, at least, two possible interpretations:
1. "If non-nil, USE THE VALUE OF EDEBUG-PRINT-LENGTH FOR THE default value of 'print-length' for printing results in Edebug."
2. "If non-nil, USE THE default value of 'print-length' for printing results in Edebug."
As you point out, the first meaning is the intended one based on the implementation. I read it according to the second interpretation.
Without getting hung up on why it's ambiguous, I hope I've made the case that it is ambiguous.
I've updated the patch to use the same wording as 'print-length' and 'print-level' which hopefully makes things clear. The current docstring felt it necessary to explicitly mention "for printing results in Edebug" and I've tried to preserve that in the suggested changes.
--
Matt Trzcinski
Emacs Org contributor (ob-shell)
Learn more about Org mode at https://orgmode.org
Support Org development at https://liberapay.com/org-mode
[-- Attachment #2: v02-fix-incorrect-edebug-docstring.diff --]
[-- Type: application/octet-stream, Size: 931 bytes --]
diff --git a/lisp/emacs-lisp/edebug.el b/lisp/emacs-lisp/edebug.el
index 4c7dbb4ef8c..8be066d0f61 100644
--- a/lisp/emacs-lisp/edebug.el
+++ b/lisp/emacs-lisp/edebug.el
@@ -193,10 +193,12 @@ Use this with caution since it is not debugged."
(defcustom edebug-print-length 50
- "If non-nil, default value of `print-length' for printing results in Edebug."
+ "Maximum length of list to print before abbreviating while in `edebug-mode'.
+When nil, behave according to `print-length'."
:type '(choice integer (const nil)))
(defcustom edebug-print-level 50
- "If non-nil, default value of `print-level' for printing results in Edebug."
+ "Maximum depth of list nesting to print before abbreviating while in `edebug-mode'.
+When nil, behave according to `print-level'."
:type '(choice integer (const nil)))
(defcustom edebug-print-circle t
"If non-nil, default value of `print-circle' for printing results in Edebug."
next prev parent reply other threads:[~2024-03-15 17:22 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-03-12 9:13 bug#69745: [PATCH] Fix incorrect Edebug docstrings Matt
2024-03-12 12:59 ` Andreas Schwab
2024-03-15 17:22 ` Matt [this message]
2024-03-16 10:43 ` Eli Zaretskii
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=18e43236053.ea8d2a62434521.1358079795129399231@excalamus.com \
--to=matt@excalamus.com \
--cc=69745@debbugs.gnu.org \
--cc=schwab@suse.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).