bug#69745: [PATCH] Fix incorrect Edebug docstrings

bug#69745: [PATCH] Fix incorrect Edebug docstrings

[Matt]

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

Hi,

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.

Thank you
--
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: fix-incorrect-edebug-docstring.diff --]
[-- Type: application/octet-stream, Size: 838 bytes --]

diff --git a/lisp/emacs-lisp/edebug.el b/lisp/emacs-lisp/edebug.el
index 4c7dbb4ef8c..a33593dca4c 100644
--- a/lisp/emacs-lisp/edebug.el
+++ b/lisp/emacs-lisp/edebug.el
@@ -193,10 +193,10 @@ 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."
+  "If nil, default value of `print-length' is used for printing results in Edebug."
   :type '(choice integer (const nil)))
 (defcustom edebug-print-level 50
-  "If non-nil, default value of `print-level' for printing results in Edebug."
+  "If nil, default value of `print-level' is used for printing results in Edebug."
   :type '(choice integer (const nil)))
 (defcustom edebug-print-circle t
   "If non-nil, default value of `print-circle' for printing results in Edebug."

bug#69745: [PATCH] Fix incorrect Edebug docstrings

[Andreas Schwab]

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.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."

bug#69745: [PATCH] Fix incorrect Edebug docstrings

[Matt]

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

bug#69745: [PATCH] Fix incorrect Edebug docstrings

[Eli Zaretskii]

> Cc: 69745 <69745@debbugs.gnu.org>
> Date: Fri, 15 Mar 2024 18:22:55 +0100
> From: Matt <matt@excalamus.com>
> 
> 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.

Thanks, I installed a variant of this on the emacs-29 branch, and I'm
therefore closing this bug.