From 9eb30cb03613ae158c870d603a05a6a6393dc485 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sat, 12 Aug 2017 10:54:32 -0700
Subject: [PATCH] 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 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
-- 
2.39.5