Document internal-use naming conventions

* doc/lispref/functions.texi (Function Names):
* doc/lispref/variables.texi (Tips for Defining):
Document naming conventions for internal-use functions and vars.
See Bug#28023#59.

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 283f74ff5d2c7734ad3ad94a654dee3a0f39e0fd..06de2e2f73062c35ce154609d3294e32a57819f7 100644 (file)
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -544,6 +544,15 @@ variable; these two uses of a symbol are independent and do not
 conflict.  (This is not the case in some dialects of Lisp, like
 Scheme.)
 
+  By convention, if a function's symbol consists of two names
+separated by @samp{--}, the function is intended for internal use and
+the first part names the file defining the function.  For example, a
+function named @code{vc-git--rev-parse} is an internal function
+defined in @file{vc-git.el}.  Internal-use functions written in C have
+names ending in @samp{-internal}, e.g., @code{bury-buffer-internal}.
+Emacs code contributed before 2018 may follow other internal-use
+naming conventions, which are being phased out.
+
 @node Defining Functions
 @section Defining Functions
 @cindex defining a function

diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi
index 2818ea067d23e3969fd5cbde5c423a4dd63d6911..7650ed4e3d8cb4ccb96670bcc0cf1d5d57dc1449 100644 (file)
--- a/doc/lispref/variables.texi
+++ b/doc/lispref/variables.texi
@@ -574,6 +574,16 @@ The value is a whole shell command.
 
 @item @dots{}-switches
 The value specifies options for a command.
+
+@item @var{prefix}--@dots{}
+The variable is intended for internal use and is defined in the file
+@file{@var{prefix}.el}.  (Emacs code contributed before 2018 may
+follow other conventions, which are being phased out.)
+
+@item @dots{}-internal
+The variable is intended for internal use and is defined in C code.
+(Emacs code contributed before 2018 may follow other conventions,
+which are being phased out.)
 @end table
 
   When you define a variable, always consider whether you should mark