Subject: RE: bug#32064: 26; doc string of `eval-last-sexp'

From: Drew Adams <[email-masked]>
Date: Thu, 5 Jul 2018 14:56:48 -0700 (PDT)

Looking at `eval-expression-get-print-arguments' and the doc string for `eval-expression', things are a bit clearer.  At least please incorporate something like what is said for `eval-expression' in the doc of `eval-last-sexp'. 

But even the `eval-expression' doc is not very good for the description of CHAR-PRINT-LIMIT.  It's not true that "unless given a positive prefix argument" a number value is printed in several... Try a prefix arg of -9, for instance.

The doc of `eval-expression-get-print-arguments' says that it determines the prefix-arg behavior for `eval-last-sexp'.  Is that true?

The doc of `eval-expression-get-print-arguments' needs to specify the logic of what it does, and that info needs to be included in the doc of `eval-expression' and (if appropriate) the doc of `eval-last-sexp'.  Or at least their doc needs to point to such info.

The doc string for `eval-expression-print-format' is not great either.  It says only what the result will "typically" look like.  It needs to specify what formats it outputs, under what conditions.

It seems that this is the situation for `eval-expression-get-print-arguments':

No prefix arg : no insert,    truncate, 127
-             : no insert,    truncate, 127
0             :    insert, no truncate, 127
-1            :    insert,    truncate, biggest fixnum
else          :    insert,    truncate, nil

Is that right?  If so, the doc should spell that out.
There's no way a user will guess this or get it easily
from the current doc.

And the various doc strings seem to suggest that the handling of the last arg, CHAR-PRINT-LIMIT by `eval-exprresion' is different from its handling by `eval-last-sexp'.  But is that true?

This is all a confusing mess, I'm afraid.  And the code (e.g. of `eval-last-sexp' and its helper `elisp--eval-last-sexp') is not very clear either.