[Emacs-diffs] master e1e8d2e: * doc/lispref/loading.texi (When to Autoload): New section.

[Glenn Morris]

branch: master
commit e1e8d2e229f48b3cee765f7cf27ae04ee4401d85
Author: Glenn Morris <address@hidden>
Commit: Glenn Morris <address@hidden>

    * doc/lispref/loading.texi (When to Autoload): New section.
---
 doc/lispref/loading.texi | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi
index d925c8c..80dcb48 100644
--- a/doc/lispref/loading.texi
+++ b/doc/lispref/loading.texi
@@ -468,6 +468,10 @@ runs the real definition as if it had been loaded all 
along.
 Autoloading can also be triggered by looking up the documentation of
 the function or macro (@pxref{Documentation Basics}).
 
address@hidden
+* When to Autoload::   When to Use Autoload.
address@hidden menu
+
   There are two ways to set up an autoloaded function: by calling
 @code{autoload}, and by writing a ``magic'' comment in the
 source before the real definition.  @code{autoload} is the low-level
@@ -699,6 +703,42 @@ symbol's new function value.  If the value of the optional 
argument
 function, only a macro.
 @end defun
 
address@hidden When to Autoload
address@hidden When to Use Autoload
address@hidden autoload, when to use
+
+Do not add an autoload comment unless it is really necessary.
+Autoloading code means it is always globally visible.  Once an item is
+autoloaded, there is no compatible way to transition back to it not
+being autoloaded (after people become accustomed to being able to use it
+without an explicit load).
+
address@hidden
address@hidden
+The most common items to autoload are the interactive entry points to a
+library.  For example, if @file{python.el} is a library defining a
+major-mode for editing Python code, autoload the definition of the
address@hidden function, so that people can simply use @kbd{M-x
+python-mode} to load the library.
+
address@hidden
+Variables usually don't need to be autoloaded.  An exception is if the
+variable on its own is generally useful without the whole defining
+library being loaded.  (An example of this might be something like
address@hidden)
+
address@hidden
+Don't autoload a user option just so that a user can set it.
+
address@hidden
+Never add an autoload @emph{comment} to silence a compiler warning in
+another file.  In the file that produces the warning, use
address@hidden(defvar foo)} to silence an undefined variable warning, and
address@hidden (@pxref{Declaring Functions}) to silence an
+undefined function warning; or require the relevant library; or use an
+explicit autoload @emph{statement}.
address@hidden itemize
+
 @node Repeated Loading
 @section Repeated Loading
 @cindex repeated loading