Commit e31dfb12 authored by Glenn Morris's avatar Glenn Morris
Browse files

(Declaring Functions): New section.

parent 193e7f80
......@@ -23,6 +23,7 @@ define them.
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 @@ do for macros. (@xref{Argument Evaluation}.)
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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment