[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#27748: 26.0.50; doc strings should be in DOC file
From: |
Ken Raeburn |
Subject: |
bug#27748: 26.0.50; doc strings should be in DOC file |
Date: |
Tue, 29 Aug 2017 06:09:09 -0400 |
Sorry it’s taken me a while to get to testing these out…
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.
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?
>> 2. In isearch, CL macro expansion results in symbols like
>> isearch--state-forward--cmacro having function definitions that
>> include the two doc strings "Access slot \"forward\" of
>> `(isearch--state (:constructor nil) [...]" and
>> "\n\n(fn CL-WHOLE-ARG CL-X)". The former string is also in DOC (with
>> "\n\n(fn CL-X)" appended) as the documentation for the function
>> isearch--state-forward.
> I think it is just an oversight, since the string was put inside the
> cl-block it is not recognized as a docstring at all. Patch 0002 drops
> the function's docstring from compiler-macro and adds a simple
> "compiler-macro for inlining `NAME'" instead.
I’m seeing the shorter string, *and* it’s stored in the DOC file.
>> 3. Undocumented functions, strange as it sounds... in files.el, function
>> file-name-non-special is defined with no documentation. In
>> files.elc, the bytecode object constructed has a doc string "\n\n(fn
>> OPERATION &rest ARGUMENTS)" instead of a (#$ . NNN) reference to a
>> separate string that make-docfile can pick up.
>
> Looks fairly trivial to fix, see patch 0003.
This one seems to be working well too.
I did a few spot checks looking at what wound up in the DOC file, and checking
the ability to load the documentation in Emacs, and things look good.
Between these three changes, the byte count for lisp/*.elc grew by 2-3%. The
DOC file is about 6% bigger, due to the strings that weren’t being picked up
before. Curiously, the generated emacs executable was just a little bit
bigger, less than 1%, but from the numbers returned by (garbage-collect) I
think that’s probably freed space.
I tested the changes out against the scratch/raeburn-startup branch as well.
In that case, the saved Lisp environment (with the more costly parsing process
than etc/DOC) shrinks by about 5%, which will probably speed up the startup
load time a little bit. There are still some doc strings left, but I’ll look
into those later.
Thanks for digging into this!
Ken