Subject: bug#60628: 29.0.60; apropos-documentation does not work for preloaded symbols

From: Stefan Monnier <[email-masked]>
Date: Fri, 13 Jan 2023 10:46:21 -0500

> The doc string of apropos-documentation does say:
>
>   Note that by default this command only searches in the file specified by
>   ‘internal-doc-file-name’; i.e., the etc/DOC file.  With C-u prefix,
>   or if ‘apropos-do-all’ is non-nil, it searches all currently defined
>   documentation strings.
>
> However, since we no longer write the doc strings of preloaded Lisp
> files to DOC, that default no longer makes sense: Emacs should not
> distinguish between built-in primitives and preloaded stuff, and it
> didn't up to and including Emacs 28.

Well, we still do as documented.  It's just that what is covered by
‘internal-doc-file-name’ is different now :-)

IOW, we should also fix the doc so it doesn't define the behavior based
on internal details such as ‘internal-doc-file-name’.  We should
probably say that by default we only search through the predefined
functions or something like that.

And as for actually (re)implementing that behavior, we can probably do
it by replacing `mapatoms` with a loop through the elements of
`load-history` corresponding to the `preloaded-file-list`.

> and in that case apropos-documentation-internal calls
> apropos-documentation-check-elc-file, which does something very
> strange: it only looks inside strings that begin with "\n#@", and
> otherwise simply ignores everything else.  Is this also a remnant from
> back when preloaded files had their doc strings in etc/DOC?

Hmm... oh I see, it's because of that Stefan dude:

    commit 900b09c0235d54d56ef5e88d04cca61bc71cbbb7
    Author: Stefan Monnier <[email-masked]>
    Date:   Fri Aug 5 08:18:04 2022 -0400
    
        bytecomp.el: Further simplifications enabled by commit 59732a83c8875c
        
        * lisp/emacs-lisp/bytecomp.el (byte-compile-output-docform): Don't
        insert a \n before the #@ docstrings since make-docfile doesn't scan
        .elc files any more.

But searching for "#@" (with or without a \n) is not a good idea anyway,
since there can be false positives and because once we've found such
a "docstring" in a .elc file the problem of finding who this docstring
belongs to again depends on details of how `bytecomp.el` decides to
print out the code.

For `emacs-29` the better option is probably to just revert the
above commit.  And for `master` we should probably rewrite the code so
it uses the POS info in the (FILE . POS) instead of searching for
#@, but that requires a significant rewrite.
Basically, we should loop through all the functions, collecting their
(FILE . POS) data, grouping them by FILE, so we end up for every
FILE with a list of (FUNCTION . POS) so we can just jump to POS without
having to search for #@ (we can still check the presence of #@ as
sanity check).

        Stefan