[Emacs-diffs] Changes to emacs/doc/lispref/functions.texi,v

[Glenn Morris]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Glenn Morris <gm>       07/11/24 03:06:15

Index: functions.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/functions.texi,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -r1.3 -r1.4
--- functions.texi      27 Oct 2007 09:07:15 -0000      1.3
+++ functions.texi      24 Nov 2007 03:06:15 -0000      1.4
@@ -23,6 +23,7 @@
                             of a symbol.
 * Obsolete Functions::    Declaring functions obsolete.
 * Inline Functions::     Defining functions that the compiler will open code.
+* Declaring Functions::   Telling the compiler that a function is defined.
 * Function Safety::       Determining whether a function is safe to call.
 * Related Topics::        Cross-references to specific Lisp primitives
                             that have a special bearing on how functions work.
@@ -1222,6 +1223,56 @@
 Inline functions can be used and open-coded later on in the same file,
 following the definition, just like macros.
 
address@hidden Declaring Functions
address@hidden Telling the Compiler that a Function is Defined
address@hidden function declaration
address@hidden declaring functions
+
+Byte-compiling a file often produces warnings about functions that are
address@hidden known to be defined} (@pxref{Compiler Errors}).  The compiler
+is technically correct, but the code is usually such that when it
+actually runs, the function @emph{will} be defined.  For example,
+byte-compiling @file{fortran.el} used to warn:
+
address@hidden
+In end of data:
+fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
+to be defined.
address@hidden example
+
+But @code{gud-find-c-expr} is only used in the function that Fortran
+mode uses for the local value of @code{gud-find-expr-function}.  This
+would only ever be called from gud, so the warning can safely be
+suppressed.  It's nice to do this, so that real warnings are more
+visible.
+
+All you need to do is add a @code{declare-function} statement before the
+first use of the function in question:
+
address@hidden
+(declare-function gud-find-c-expr "gud.el" nil)
address@hidden example
+
+This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the
+`.el' can be omitted).  The file is searched for using
address@hidden, and failing that it is expanded relative to the
+file containing the @code{declare-function} statement.  Functions
+defined in C can also be declared - @file{.c} files are expanded
+relative to the Emacs @file{src/} directory.
+
+The optional third argument specifies the argument list of
address@hidden  In this case, it takes no arguments (@code{nil}
+is different from not specifying a value).  In other cases, this might
+be something like @code{(file &optional overwrite)}.  You don't have to
+specify the argument list, but if you do the byte-compiler will check
+that the calls match the declaration.
+
+The functions @code{check-declare-file} and
address@hidden check that all the
address@hidden statements in a file or directory are true
+(i.e. that the functions @emph{are} defined in the specified files, and
+have matching argument lists, if these were specified).
+
 @node Function Safety
 @section Determining whether a Function is Safe to Call
 @cindex function safety