new repository

1 files changed, 13 insertions, 0 deletions

diff --git a/devdocs/elisp/declaring-functions.html b/devdocs/elisp/declaring-functions.html
new file mode 100644
index 00000000..42ef764c
--- /dev/null
+++ b/devdocs/elisp/declaring-functions.html
@@ -0,0 +1,13 @@
+ <h3 class="section">Telling the Compiler that a Function is Defined</h3>    <p>Byte-compiling a file often produces warnings about functions that the compiler doesn’t know about (see <a href="compiler-errors">Compiler Errors</a>). 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 <samp>simple.el</samp> used to warn: </p> <div class="example"> <pre class="example">simple.el:8727:1:Warning: the function ‘shell-mode’ is not known to be
+    defined.
+</pre>
+</div> <p>In fact, <code>shell-mode</code> is used only in a function that executes <code>(require 'shell)</code> before calling <code>shell-mode</code>, so <code>shell-mode</code> 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 <code>declare-function</code>. </p> <p>All you need to do is add a <code>declare-function</code> statement before the first use of the function in question: </p> <div class="example"> <pre class="example">(declare-function shell-mode "shell" ())
+</pre>
+</div> <p>This says that <code>shell-mode</code> is defined in <samp>shell.el</samp> (the ‘<samp>.el</samp>’ can be omitted). The compiler takes for granted that that file really defines the function, and does not check. </p> <p>The optional third argument specifies the argument list of <code>shell-mode</code>. In this case, it takes no arguments (<code>nil</code> is different from not specifying a value). In other cases, this might be something like <code>(file &amp;optional overwrite)</code>. You don’t have to specify the argument list, but if you do the byte compiler can check that the calls match the declaration. </p> <dl> <dt id="declare-function">Macro: <strong>declare-function</strong> <em>function file &amp;optional arglist fileonly</em>
+</dt> <dd><p>Tell the byte compiler to assume that <var>function</var> is defined in the file <var>file</var>. The optional third argument <var>arglist</var> is either <code>t</code>, meaning the argument list is unspecified, or a list of formal parameters in the same style as <code>defun</code>. An omitted <var>arglist</var> defaults to <code>t</code>, not <code>nil</code>; this is atypical behavior for omitted arguments, and it means that to supply a fourth but not third argument one must specify <code>t</code> for the third-argument placeholder instead of the usual <code>nil</code>. The optional fourth argument <var>fileonly</var> non-<code>nil</code> means check only that <var>file</var> exists, not that it actually defines <var>function</var>. </p></dd>
+</dl>   <p>To verify that these functions really are declared where <code>declare-function</code> says they are, use <code>check-declare-file</code> to check all <code>declare-function</code> calls in one source file, or use <code>check-declare-directory</code> check all the files in and under a certain directory. </p> <p>These commands find the file that ought to contain a function’s definition using <code>locate-library</code>; if that finds no file, they expand the definition file name relative to the directory of the file that contains the <code>declare-function</code> call. </p> <p>You can also say that a function is a primitive by specifying a file name ending in ‘<samp>.c</samp>’ or ‘<samp>.m</samp>’. This is useful only when you call a primitive that is defined only on certain systems. Most primitives are always defined, so they will never give you a warning. </p> <p>Sometimes a file will optionally use functions from an external package. If you prefix the filename in the <code>declare-function</code> statement with ‘<samp>ext:</samp>’, then it will be checked if it is found, otherwise skipped without error. </p> <p>There are some function definitions that ‘<samp>check-declare</samp>’ does not understand (e.g., <code>defstruct</code> and some other macros). In such cases, you can pass a non-<code>nil</code> <var>fileonly</var> argument to <code>declare-function</code>, meaning to only check that the file exists, not that it actually defines the function. Note that to do this without having to specify an argument list, you should set the <var>arglist</var> argument to <code>t</code> (because <code>nil</code> means an empty argument list, as opposed to an unspecified one). </p><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Declaring-Functions.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Declaring-Functions.html</a>
+  </p>
+</div>