bug-gnu-emacs
[Top][All Lists]
Advanced

[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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]