changeset 86383:382d8b0539b2

(Declaring Functions): New section.

--- a/doc/lispref/functions.texi	Sat Nov 24 00:57:26 2007 +0000
+++ b/doc/lispref/functions.texi	Sat Nov 24 03:06:15 2007 +0000
@@ -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.
 
+@node Declaring Functions
+@section Telling the Compiler that a Function is Defined
+@cindex function declaration
+@cindex declaring functions
+
+Byte-compiling a file often produces warnings about functions that are
+@samp{not 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:
+
+@example
+In end of data:
+fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
+to be defined.
+@end 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:
+
+@example
+(declare-function gud-find-c-expr "gud.el" nil)
+@end 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
+@code{locate-library}, 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
+@code{gud-find-c-expr}.  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
+@code{check-declare-directory} check that all the
+@code{declare-function} 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