From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.ciao.gmane.io!not-for-mail From: Emanuel Berg via Users list for the GNU Emacs text editor Newsgroups: gmane.emacs.help Subject: `declare-function' docu (was: Re: Bookmarks in EWW) Date: Wed, 25 Mar 2020 04:45:20 +0100 Message-ID: <877dz92j3j.fsf_-_@ebih.ebihd> References: <878sjrfh2m.fsf@mbork.pl> <871rpipzwa.fsf@web.de> <87tv2d3zii.fsf@web.de> Reply-To: Emanuel Berg Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="ciao.gmane.io:159.69.161.202"; logging-data="22418"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.1 (gnu/linux) To: help-gnu-emacs@gnu.org Cancel-Lock: sha1:YWSakZINj/n/UJ/W13wUkVYrksA= Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org Wed Mar 25 04:45:53 2020 Return-path: Envelope-to: geh-help-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jGwzJ-0005jV-4Y for geh-help-gnu-emacs@m.gmane-mx.org; Wed, 25 Mar 2020 04:45:53 +0100 Original-Received: from localhost ([::1]:58840 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jGwzI-0008O0-6p for geh-help-gnu-emacs@m.gmane-mx.org; Tue, 24 Mar 2020 23:45:52 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:49657) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jGwyv-0008Nr-NU for help-gnu-emacs@gnu.org; Tue, 24 Mar 2020 23:45:30 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jGwyu-0005Q0-Cy for help-gnu-emacs@gnu.org; Tue, 24 Mar 2020 23:45:29 -0400 Original-Received: from ciao.gmane.io ([159.69.161.202]:37834) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1jGwyu-0005Ov-7J for help-gnu-emacs@gnu.org; Tue, 24 Mar 2020 23:45:28 -0400 Original-Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1jGwys-0005B3-DE for help-gnu-emacs@gnu.org; Wed, 25 Mar 2020 04:45:26 +0100 X-Injected-Via-Gmane: http://gmane.org/ Mail-Followup-To: help-gnu-emacs@gnu.org Mail-Copies-To: never X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 159.69.161.202 X-BeenThere: help-gnu-emacs@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Users list for the GNU Emacs text editor List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "help-gnu-emacs" Xref: news.gmane.io gmane.emacs.help:122651 Archived-At: 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