mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-11-24 07:20:37 +00:00
Code Issues Releases Activity

Document internal-use naming conventions

Browse Source 
* 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.
This commit is contained in:
Paul Eggert 2017-08-12 10:54:32 -07:00
parent 81e22163eb
commit 9eb30cb036
2 changed files with 19 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
doc/lispref/functions.texi
View File

@ -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

10
doc/lispref/variables.texi
View File

@ -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