Subject: Re: bug#28023: fix make-temp-file race on local host

From: Paul Eggert <[email-masked]>
Date: Sat, 12 Aug 2017 10:57:26 -0700

Eli Zaretskii wrote:
> I think the prefix that comes from the file where the function is
> defined is more of a Lisp convention, and the -internal convention is
> more for C implementations.

I see lots of exceptions to these conventions, presumably either because 
developers don't know the intent or because the code was written before the 
conventions were established. Still, it's better to document the intent so I 
installed the attached patch to do that. I'll adjust the make-temp-file patch 
accordingly.
From 57c2de6fce73b77081e59d0527b12f158bac758a Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
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 283f74f..06de2e2 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -544,6 +544,15 @@ Function Names
 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 @@ Tips for Defining
 
 @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.7.4