[Emacs-diffs] master 9eb30cb: Document internal-use naming conventions

[Paul Eggert]

branch: master
commit 9eb30cb03613ae158c870d603a05a6a6393dc485
Author: Paul Eggert <address@hidden>
Commit: Paul Eggert <address@hidden>

    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.
---
 doc/lispref/functions.texi |  9 +++++++++
 doc/lispref/variables.texi | 10 ++++++++++
 2 files changed, 19 insertions(+)

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 283f74f..06de2e2 100644
--- 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 2818ea0..7650ed4 100644
--- 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.
+
address@hidden @address@hidden
+The variable is intended for internal use and is defined in the file
address@hidden@var{prefix}.el}.  (Emacs code contributed before 2018 may
+follow other conventions, which are being phased out.)
+
address@hidden @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