bug#23258: 25.1.50; The docstring of with-eval-after-load needs improvement

bug#23258: 25.1.50; The docstring of with-eval-after-load needs improvement

[Harald Hanche-Olsen]

The docstring for with-eval-after-load gives only a cursory description of the FILE argument. The docstring of the wrapped function eval-after-load, however, is much more comprehensive. It should either be included in the docstring of with-eval-after-load, or the docstring for with-eval-after-load should refer the reader to eval-after-load for further details. (The latter option is far better, IMO.)

As evidence of the harm done by the incomplete documentation, I offer this link:

http://emacs.stackexchange.com/q/21540/962

– Harald

In GNU Emacs 25.1.50.1 (x86_64-apple-darwin15.3.0, NS appkit-1404.34 Version 10.11.3 (Build 15D21))
 of 2016-03-16 built on frigg
Repository revision: b48197d8eda0d4fe221a128d862807d804e2ebf0
Windowing system distributor 'Apple', version 10.3.1404
Configured using:
 'configure --with-ns'

bug#23258: 25.1.50; The docstring of with-eval-after-load needs improvement

[Eli Zaretskii]

> From: Harald Hanche-Olsen <hanche@math.ntnu.no>
> Date: Sun, 10 Apr 2016 06:43:09 +0000
> 
> The docstring for with-eval-after-load gives only a cursory description of the FILE argument. The docstring of the wrapped function eval-after-load, however, is much more comprehensive. It should either be included in the docstring of with-eval-after-load, or the docstring for with-eval-after-load should refer the reader to eval-after-load for further details. (The latter option is far better, IMO.)

Fixed.

For such simple bugs, I'd encourage people to submit patches rather
than just tell how to fix the problem.  Thanks in advance.

bug#23258: 25.1.50; The docstring of with-eval-after-load needs improvement

[Harald Hanche-Olsen]

On 10 April 2016 at 18:18:12, Eli Zaretskii (eliz@gnu.org) wrote:

> For such simple bugs, I'd encourage people to submit patches rather
> than just tell how to fix the problem. Thanks in advance.

Okay. By that, do you mean include a patch with the bug report, or is there some other mechanism for submitting patches that I am not aware of?

– Harald

bug#23258: 25.1.50; The docstring of with-eval-after-load needs improvement

[Eli Zaretskii]

> X-Spam-Status: No, score=-2.5 required=5.0 tests=BAYES_50,RCVD_IN_DNSWL_MED,
> 	RP_MATCHES_RCVD autolearn=disabled version=3.3.2
> From: Harald Hanche-Olsen <hanche@math.ntnu.no>
> CC: "23258-done@debbugs.gnu.org" <23258-done@debbugs.gnu.org>
> Date: Sun, 10 Apr 2016 16:38:02 +0000
> Accept-Language: en-US, nb-NO
> 
> On 10 April 2016 at 18:18:12, Eli Zaretskii (eliz@gnu.org) wrote:
> 
> > For such simple bugs, I'd encourage people to submit patches rather
> > than just tell how to fix the problem. Thanks in advance.
> 
> Okay. By that, do you mean include a patch with the bug report, or is there some other mechanism for submitting patches that I am not aware of?

Just include it.  The "git format-patch" form is preferred, but a
simple patch is also okay.

TIA

bug#23258: 25.1.50; The docstring of with-eval-after-load needs improvement

[Drew Adams]

> The docstring for with-eval-after-load gives only a cursory description
> of the FILE argument. The docstring of the wrapped function eval-after-
> load, however, is much more comprehensive. It should either be included
> in the docstring of with-eval-after-load, or the docstring for with-eval-
> after-load should refer the reader to eval-after-load for further
> details. (The latter option is far better, IMO.)
> 
> As evidence of the harm done by the incomplete documentation, I offer
> this link:
> 
> http://emacs.stackexchange.com/q/21540/962

+1  (Thank you, Harald.)  Let me add a bit about this doc.

AFAICT, there was no great need for creating this macro
(and essentially telling users to prefer it over function
`eval-after-load').  The "need" seems to have been only the
fact that some users were not quoting arguments that they
did not want to have evaluated.

But having done that, whoever did it seems to have dropped
the ball wrt documenting it.  At the least, its doc should
refer to `eval-after-load' (and vice versa presumably).

As for the changes that were made to the doc string of
`eval-after-load' at the same time:

1. This mystery sentence was added - at the very top, no less:

     This function has a compiler macro.

   I had to search the source code to find out what that is
   meant to mean - means for a function to have a "compiler
   macro", and even what a "compiler macro" is.

   And having found property `compiler-macro' used in the
   source code, I had to search the Elisp manual for that
   (there is no index entry for it).  Finally, I found some
   light in node `Declare Form'.

   It cannot be clear to readers of `C-h f eval-after-load'
   what that mystery sentence is for.  If we are going to
   include mention of this we should use English to get across
   the real point, which is presumably to say that a call to
   the function might be expanded by the compiler in different
   ways.

   I admit that I still do not understand why we would tell
   users this in `C-h f' output.  And perhaps I still do not
   fully grasp the message.  What seems clear to me is that
   most users will have NO CLUE what this mystery sentence
   (again, at the top of the help output, no less) is trying
   to tell them, much less why it is (or isn't) important.

2. FORM can now be a function, and what it can be is described
   before the description of what FILE can be.  These are out
   of order.  (OK, not very important.)

As for the doc in the Elisp manual: `eval-after-load' is no
longer even mentioned, except for these nodes: (1) `Hooks for
Loading`, (2) `Coding Conventions', and (3) `Named Features'.

The doc should be cleaned up to be coherent.  And (IMHO) it
_should_ document `eval-after-load' - far more important than
documenting `with-eval-after-load'.  Mentioning the latter
does not replace describing the former.

1. Node `Hooks for Loading` says:

     Normally, well-designed Lisp programs should not use
     ‘eval-after-load’....

   Perhaps it meant to say `with-eval-after-load' here?
   If not, why not?

2. Node `Coding Conventions' says:

     Avoid using ‘eval-after-load’ in libraries and packages
     (*note Hooks for Loading::).  This feature is meant for
     personal customizations; using it in a Lisp program is
     unclean...

   Again, why only `eval-after-load' for such a caution, and
   not (also) `with-eval-after-load'?

3. Node `Named Features' says:

     The direct effect of calling ‘provide’ is if not already
     in FEATURES then to add FEATURE to the front of that list
     and call any ‘eval-after-load’ code waiting for it (*note
     Hooks for Loading::).

   Now clearly it is correct to speak of `eval-after-load'
   here, and not `with-eval-after-load'.  But is the same not
   true pretty much everywhere?  Ultimately, the _behavior_
   is that of `eval-after-load' - `with-eval-after-load' is
   only a wrapper.

Finally, the Emacs manual makes no reference to either the
macro or the function, except for this, in node `Foldout':

  To use the Foldout package, you can type ‘M-x load-library
  <RET> foldout <RET>’; or you can arrange for to do that
  automatically by putting the following in your init file:

     (eval-after-load "outline" '(require 'foldout))

Is that mention appropriate, or should it be removed?
What's so special about library `foldout.el' in this regard?

bug#23258: 25.1.50; The docstring of with-eval-after-load needs improvement

[Eli Zaretskii]

> Date: Sun, 10 Apr 2016 09:21:46 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> As for the changes that were made to the doc string of
> `eval-after-load' at the same time:
> 
> 1. This mystery sentence was added - at the very top, no less:
> 
>      This function has a compiler macro.

There's no such text in the doc string, it is created by the
documentation system.

bug#23258: 25.1.50; The docstring of with-eval-after-load needs improvement

[Drew Adams]

> > The docstring for with-eval-after-load gives only a cursory description
> of the FILE argument. The docstring of the wrapped function eval-after-
> load, however, is much more comprehensive. It should either be included in
> the docstring of with-eval-after-load, or the docstring for with-eval-
> after-load should refer the reader to eval-after-load for further details.
> (The latter option is far better, IMO.)
> 
> Fixed.
> 
> For such simple bugs, I'd encourage people to submit patches rather
> than just tell how to fix the problem.  Thanks in advance.

Your quick closing coincided with my reply.  There is more to
this than just what was mentioned in the bug report.  Do you
want me to file a separate bug report with the feedback I
provided to this one?

bug#23258: 25.1.50; The docstring of with-eval-after-load needs improvement

[Eli Zaretskii]

> Date: Sun, 10 Apr 2016 09:26:25 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 23258-done@debbugs.gnu.org
> 
> Your quick closing coincided with my reply.  There is more to
> this than just what was mentioned in the bug report.  Do you
> want me to file a separate bug report with the feedback I
> provided to this one?

Separate bug, of course.  It has nothing to do with this one.

bug#23258: 25.1.50; The docstring of with-eval-after-load needs improvement

[Drew Adams]

> > As for the changes that were made to the doc string of
> > `eval-after-load' at the same time:
> >
> > 1. This mystery sentence was added - at the very top, no less:
> >
> >      This function has a compiler macro.
> 
> There's no such text in the doc string, it is created by the
> documentation system.

Yes, I know that.  I think I made it clear in the rest of my
message, stating that I was referring to the output of `C-h f'
here.  But yes, the intro sentence above misleadingly spoke
of the "doc string".

bug#23258: 25.1.50; The docstring of with-eval-after-load needs improvement

[Drew Adams]

> > Your quick closing coincided with my reply.  There is more to
> > this than just what was mentioned in the bug report.  Do you
> > want me to file a separate bug report with the feedback I
> > provided to this one?
> 
> Separate bug, of course.  It has nothing to do with this one.

Done - bugs #23262 and #23264.