[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
`declare-function' docu (was: Re: Bookmarks in EWW)
From: |
Emanuel Berg |
Subject: |
`declare-function' docu (was: Re: Bookmarks in EWW) |
Date: |
Wed, 25 Mar 2020 04:45:20 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/26.1 (gnu/linux) |
Michael Heerdegen wrote:
> (declare-function ...
I didn't know about `declare-function', so I used `C-h f' to
find out that... err... then I followed the link, provided by
the help page (great!), which lead to the info pages,
specifically this one
(info "(elisp) Declaring Functions")
^eval me
and it says:
Byte-compiling a file often produces warnings about
functions that the compiler doesn’t know about.
Sometimes this indicates a real problem, but usually the
functions in question are defined in other files which
would be loaded if that code is run. For example,
byte-compiling ‘simple.el’ used to warn:
simple.el:8727:1:Warning: the function ‘shell-mode’ is not known to be
defined.
In fact, ‘shell-mode’ is used only in a function that
executes ‘(require 'shell)’ before calling ‘shell-mode’,
so ‘shell-mode’ will be defined properly at run-time.
When you know that such a warning does not indicate a real
problem, it is good to suppress the warning. That makes
new warnings which might mean real problems more visible.
You do that with ‘declare-function’.
All you need to do is add a ‘declare-function’ statement
before the first use of the function in question:
(declare-function shell-mode "shell" ())
This says that ‘shell-mode’ is defined in ‘shell.el’ (the
‘.el’ can be omitted). The compiler takes for granted that
that file really defines the function, and does not check.
[...]
That's were I stopped reading!
Here we see the benefits of links from the docstring-based
help system to the info pages, which IMO should always be
present when available. When this issue was brought up last
time around, there was the argument that links would increase
the size of Emacs. However, if one is really concerned with
size at that level, cannot the hyperlinks be computed
on-the-fly? That would provide the functionality while not
increasing the size - well, not lineary, at least! And if
anyone was concerned with speed, we could have an option to
switch it on and off...
Also, the two pieces of documentation seem to have completely
different focus points? The docstring help focuses on
technical aspects instead of the purpose, while the info just
says instantly, ~"use this to shut the byte-compiler up".
--
underground experts united
http://user.it.uu.se/~embe8573
https://dataswamp.org/~incal
- Bookmarks in EWW, Marcin Borkowski, 2020/03/23
- RE: Bookmarks in EWW, Drew Adams, 2020/03/23
- Re: Bookmarks in EWW, Michael Heerdegen, 2020/03/23
- Re: Bookmarks in EWW, Stefan Monnier, 2020/03/25
- Re: Bookmarks in EWW, Michael Heerdegen, 2020/03/25
- Re: Bookmarks in EWW, Stefan Monnier, 2020/03/26
- Re: Bookmarks in EWW, Michael Heerdegen, 2020/03/26
- Re: Bookmarks in EWW, Stefan Monnier, 2020/03/26
- Re: Bookmarks in EWW, Michael Heerdegen, 2020/03/27
- Re: Bookmarks in EWW, Stefan Monnier, 2020/03/27