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

[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




reply via email to

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