bug#27748: 26.0.50; doc strings should be in DOC file

[npostavs@users.sourceforge.net]

Ken Raeburn <raeburn@raeburn.org> writes:

> Sorry it’s taken me a while to get to testing these out…

Hah, no problem.  I confess it's been on my todo list to test out your
scratch/raeburn-startup branch for an even longer while...

> On Aug 20, 2017, at 18:05, npostavs@users.sourceforge.net wrote:
>> 
>>> 1. defcustom doc strings from files compiled with lexical binding.
>
>> With patch 0001 defcustoms which are compiled to bytecode now produce
>> dynamic docstrings which make-doc can digest (note that I had to change
>> make-doc a bit for this, but the .elc format remains the same as far as
>> the Emacs loading it is concerned.  See the commit message for details).
>
> I think I like the new format.  It’s a little bit bigger, but it may
> load faster, as we can do one big fseek at the beginning of the file
> (thus not even loading a lot of those pages) rather than lots of small
> ones as we go along.

Indeed, that was my thought too.  I haven't measured anything though.

> Will this new make-docfile play nicely with files compiled with
> byte-compile-dynamic, where byte code is mixed in with the usual doc
> strings?  Or if we decide to make lambdas (which have “(fn…)” doc
> strings by default but have no names to associate with them in DOC)
> load their doc strings dynamically from the .elc file?

Hmm, it will not.  We would have to add a "nameless" type I guess,
something like ^_A^_anonymous docstring here...^_.

I pushed patches [2: bc5d96a0b2] and [3: 160295867d] to master, since
they are pretty straightforward bugfixes.

[2: bc5d96a0b2]: 2017-08-30 20:07:39 -0400
  Drop docstrings from cl-defsubst produced inline bodies (Bug#27748)
  http://git.savannah.gnu.org/cgit/emacs.git/commit/?id=bc5d96a0b2a1dccf7eeeec459e40d21b54c977f4>

[3: 160295867d]: 2017-08-30 20:07:39 -0400
  Support lazy loading for autogenerated usage docstrings too (Bug#27748)
  http://git.savannah.gnu.org/cgit/emacs.git/commit/?id=160295867de98241a16f2ede93da7e825ed4406b