From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sat, 12 Aug 2017 17:54:32 +0000 (-0700)
Subject: Document internal-use naming conventions
X-Git-Tag: emacs-26.0.90~478
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=9eb30cb03613ae158c870d603a05a6a6393dc485;p=emacs.git

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 283f74ff5d2..06de2e2f730 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 2818ea067d2..7650ed4e3d8 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.
+
+@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