bug#26888: 25.2; doc of `with-eval-after-load'

bug#26888: 25.2; doc of `with-eval-after-load'

[Drew Adams]

1. The doc does not make clear that argument LIBRARY is evaluated or
that argument BODY is _not_ evaluated, at the time the overall sexp is
evaluated.

2. The doc string and the Elisp manual should use the same name, LIBRARY
or FILE.

3. There is lots of information about the behavior that is missing from
the doc of `with-eval-after-load' but is present in the doc of
`eval-after-load'.  They don't behave the same, but the latter makes use
of the former.  You cannot understand all of the the behavior of the
former without consulting the doc (or the code) of the latter.

We've done users a disservice by removing the doc for `eval-after-load'
from the manual and by not, at least, providing equivalent information
for `with-eval-after-load'.  We've apparently intentionally tried to
"dumb this down", but users deserve better help than this.

At the very least, the doc for `with-eval-after-load' should refer to
the more complete doc of `eval-after-load', and explain that the former
just expands to the latter after wrapping BODY in an anonymous function.


In GNU Emacs 25.2.1 (x86_64-w64-mingw32)
 of 2017-04-24
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --without-compress-install 'CFLAGS=-O2
 -static -g3''

bug#26888: 25.2; doc of `with-eval-after-load'

[Lars Ingebrigtsen]

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

> At the very least, the doc for `with-eval-after-load' should refer to
> the more complete doc of `eval-after-load', and explain that the former
> just expands to the latter after wrapping BODY in an anonymous function.

The doc string here is now:

FILE is normally a feature name, but it can also be a file name,
in case that file does not provide any feature.  See `eval-after-load'
for more details about the different forms of FILE and their semantics."

So I don't think there's more to be done here, and I'm closing this bug
report.

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