bug#19114: 25.0.50; doc string of `eval-expression-print-format' is inappropriate

bug#19114: 25.0.50; doc string of `eval-expression-print-format' is inappropriate

[Drew Adams]

The doc string says "Return a formatted string which is displayed in the
echo area..."  This is quite misleading.  It can easily give the
impression that this function displays the returned value in the echo
area.  THIS function does not with the formatted string, besides
returning it.  It displays nothing.  Please DTRT.

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

bug#19114: 25.0.50; doc string of `eval-expression-print-format' is inappropriate

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> The doc string says "Return a formatted string which is displayed in the
> echo area..."  This is quite misleading.  It can easily give the
> impression that this function displays the returned value in the echo
> area.  THIS function does not with the formatted string, besides
> returning it.  It displays nothing.  Please DTRT.

(defun eval-expression-print-format (value)
  "Format VALUE as a result of evaluated expression.
Return a formatted string which is displayed in the echo area
in addition to the value printed by prin1 in functions which
display the result of expression evaluation."

I don't know quite what they're trying to express here...

But then again, I don't understand the meaning of the function, either:

  (if (and (integerp value)
	   (or (eq standard-output t)
	       (zerop (prefix-numeric-value current-prefix-arg))))
      (let ((char-string
	     (if (and (characterp value)
		      (char-displayable-p value))
		 (prin1-char value))))
        (if char-string
            (format " (#o%o, #x%x, %s)" value value char-string)
          (format " (#o%o, #x%x)" value value)))))

(eval-expression-print-format 1)
C-x C-e
" (#o1, #x1, ?\\C-a)" appears in *Messages*

(eval-expression-print-format 1)
C-u C-x C-e
=> nil
Nothing in *Messages*

(eval-expression-print-format 'foo)
nil

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#19114: 25.0.50; doc string of `eval-expression-print-format' is inappropriate

[Michael Heerdegen]

Lars Ingebrigtsen <larsi@gnus.org> writes:


> I don't know quite what they're trying to express here...

Seems this function does only return a non-nil value for integer
values.  It seems to be responsible for printing it in octal, hex, and
as a character.


> (eval-expression-print-format 1)
> C-x C-e
> " (#o1, #x1, ?\\C-a)" appears in *Messages*

C-x C-e prints the return value.  The function doesn't print by itself
(AFAIU this is what Drew wanted to be made clearer).


> (eval-expression-print-format 1)
> C-u C-x C-e
> => nil
> Nothing in *Messages*

Expected, I think.

> (eval-expression-print-format 'foo)
> nil

Because foo is not an integer.


Michael.

bug#19114: 25.0.50; doc string of `eval-expression-print-format' is inappropriate

[Lars Ingebrigtsen]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> Lars Ingebrigtsen <larsi@gnus.org> writes:
>
>> I don't know quite what they're trying to express here...
>
> Seems this function does only return a non-nil value for integer
> values.  It seems to be responsible for printing it in octal, hex, and
> as a character.

Yes.  Its name and its doc string seems to suggest that it's doing
something general, but it's doing something very particular: Formatting
an "extended integer" explanation in some circumstances.

I'll rewrite the doc string to say that it's doing that.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#19114: 25.0.50; doc string of `eval-expression-print-format' is inappropriate

[Michael Heerdegen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> I'll rewrite the doc string to say that it's doing that.

Thank you for caring.

One thing: You wrote

  This function is used by functions like `prin1' that display the
  result of expression evaluation.

I don't know much about the C internals, so I could be wrong - but I
don't think this is true: I think `prin1' doesn't call
`eval-expression-print-format'.  The command `eval-expression' does,
however, to give a nicer feedback.


Thanks,

Michael.

bug#19114: 25.0.50; doc string of `eval-expression-print-format' is inappropriate

[Lars Ingebrigtsen]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> (defun eval-expression-print-format (value)
>   "Format VALUE as a result of evaluated expression.
> Return a formatted string which is displayed in the echo area
> in addition to the value printed by prin1 in functions which
> display the result of expression evaluation."
>
> I don't know quite what they're trying to express here...

Oh, I understood while rewriting.  :-)  It means that this function is
used by functions like `prin1' which typically display something in the
echo area.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#19114: 25.0.50; doc string of `eval-expression-print-format' is inappropriate

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Sat, 30 Apr 2016 17:13:45 +0200
> Cc: 19114@debbugs.gnu.org
> 
> Drew Adams <drew.adams@oracle.com> writes:
> 
> > The doc string says "Return a formatted string which is displayed in the
> > echo area..."  This is quite misleading.  It can easily give the
> > impression that this function displays the returned value in the echo
> > area.  THIS function does not with the formatted string, besides
> > returning it.  It displays nothing.  Please DTRT.
> 
> (defun eval-expression-print-format (value)
>   "Format VALUE as a result of evaluated expression.
> Return a formatted string which is displayed in the echo area
> in addition to the value printed by prin1 in functions which
> display the result of expression evaluation."
> 
> I don't know quite what they're trying to express here...

Much ado about nothing, if you ask me.  Replace "is displayed" with
"will be displayed", and I think the intent is more clear.

> But then again, I don't understand the meaning of the function, either:
> 
>   (if (and (integerp value)
> 	   (or (eq standard-output t)
> 	       (zerop (prefix-numeric-value current-prefix-arg))))
>       (let ((char-string
> 	     (if (and (characterp value)
> 		      (char-displayable-p value))
> 		 (prin1-char value))))
>         (if char-string
>             (format " (#o%o, #x%x, %s)" value value char-string)
>           (format " (#o%o, #x%x)" value value)))))
> 
> (eval-expression-print-format 1)
> C-x C-e
> " (#o1, #x1, ?\\C-a)" appears in *Messages*
> 
> (eval-expression-print-format 1)
> C-u C-x C-e
> => nil
> Nothing in *Messages*

Try "C-u 0", like the code says.

bug#19114: 25.0.50; doc string of `eval-expression-print-format' is inappropriate

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Much ado about nothing, if you ask me. 

No ado meant.  :-)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no