[FFmpeg-cvslog] doc/developer.texi: extend and update naming conventions

[Anton Khirnov]

ffmpeg | branch: master | Anton Khirnov <anton at khirnov.net> | Tue Nov 15 09:22:46 2022 +0100| [14c60935280d81d333ba9e19f0ebd39f16d8c778] | committer: Anton Khirnov

doc/developer.texi: extend and update naming conventions

Bring it up to date with current practice, as the current text does not
cover everything. Drop the reference to unprefixed exported symbols,
which do not exist anymore.

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=14c60935280d81d333ba9e19f0ebd39f16d8c778
---

 doc/developer.texi | 43 +++++++++++++++++++++++++++----------------
 1 file changed, 27 insertions(+), 16 deletions(-)

diff --git a/doc/developer.texi b/doc/developer.texi
index 02086f409f..31b485b0f6 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -180,39 +180,50 @@ int myfunc(int my_parameter)
 @end example
 
 @section Naming conventions
-All names should be composed with underscores (_), not CamelCase. For example,
- at samp{avfilter_get_video_buffer} is an acceptable function name and
- at samp{AVFilterGetVideo} is not. The exception from this are type names, like
-for example structs and enums; they should always be in CamelCase.
 
-There are the following conventions for naming variables and functions:
+Names of functions, variables, and struct members must be lowercase, using
+underscores (_) to separate words. For example, @samp{avfilter_get_video_buffer}
+is an acceptable function name and @samp{AVFilterGetVideo} is not.
 
- at itemize @bullet
- at item
-For local variables no prefix is required.
+Struct, union, enum, and typedeffed type names must use CamelCase. All structs
+and unions should be typedeffed to the same name as the struct/union tag, e.g.
+ at code{typedef struct AVFoo @{ ... @} AVFoo;}. Enums are typically not
+typedeffed.
 
+Enumeration constants and macros must be UPPERCASE, except for macros
+masquerading as functions, which should use the function naming convention.
+
+All identifiers in the libraries should be namespaced as follows:
+ at itemize @bullet
 @item
-For file-scope variables and functions declared as @code{static}, no prefix
-is required.
+No namespacing for identifiers with file and lower scope (e.g. local variables,
+static functions), and struct and union members,
 
 @item
-For variables and functions visible outside of file scope, but only used
-internally by a library, an @code{ff_} prefix should be used,
-e.g. @samp{ff_w64_demuxer}.
+The @code{ff_} prefix must be used for variables and functions visible outside
+of file scope, but only used internally within a single library, e.g.
+ at samp{ff_w64_demuxer}. This prevents name collisions when FFmpeg is statically
+linked.
 
 @item
 For variables and functions visible outside of file scope, used internally
 across multiple libraries, use @code{avpriv_} as prefix, for example,
 @samp{avpriv_report_missing_feature}.
 
+ at item
+All other internal identifiers, like private type or macro names, should be
+namespaced only to avoid possible internal conflicts. E.g. @code{H264_NAL_SPS}
+vs. @code{HEVC_NAL_SPS}.
+
 @item
 Each library has its own prefix for public symbols, in addition to the
 commonly used @code{av_} (@code{avformat_} for libavformat,
 @code{avcodec_} for libavcodec, @code{swr_} for libswresample, etc).
 Check the existing code and choose names accordingly.
-Note that some symbols without these prefixes are also exported for
-retro-compatibility reasons. These exceptions are declared in the
- at code{lib<name>/lib<name>.v} files.
+
+ at item
+Other public identifiers (struct, union, enum, macro, type names) must use their
+library's public prefix (@code{AV}, @code{Sws}, or @code{Swr}).
 @end itemize
 
 Furthermore, name space reserved for the system should not be invaded.