doc/dev: clarify public symbols prefixes.

[ffmpeg] / doc / developer.texi

diff --git a/doc/developer.texi b/doc/developer.texi
index a108da7adce3bc942a8d79265e0c8e457c979b24..5acdce9643079da14a8f74328d282eb68f5b61e4 100644 (file)
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -147,29 +147,41 @@ GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
 @end itemize
 
 @subsection Naming conventions
-All names are using underscores (_), not CamelCase. For example, @samp{avfilter_get_video_buffer} is
-a valid function name and @samp{AVFilterGetVideo} is not. The exception from this are type names, like
+All names should be composed with underscores (_), not CamelCase. For example,
+@samp{avfilter_get_video_buffer} is an acceptable function name and
+@samp{AVFilterGetVideo} is not. The exception from this are type names, like
 for example structs and enums; they should always be in the CamelCase
 
-
-There are following conventions for naming variables and functions:
+There are the following conventions for naming variables and functions:
 @itemize @bullet
 @item
 For local variables no prefix is required.
 @item
-For variables and functions declared as @code{static} no prefixes are required.
+For variables and functions declared as @code{static} no prefix is required.
 @item
-For variables and functions used internally by the library, @code{ff_} prefix
-should be used.
-For example, @samp{ff_w64_demuxer}.
+For variables and functions used internally by a library an @code{ff_}
+prefix should be used, e.g. @samp{ff_w64_demuxer}.
 @item
 For variables and functions used internally across multiple libraries, use
 @code{avpriv_}. For example, @samp{avpriv_aac_parse_header}.
 @item
-For exported names, each library has its own prefixes. Just check the existing
-code and name accordingly.
+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
+@code{lib<name>/lib<name>.v} files.
 @end itemize
 
+Furthermore, name space reserved for the system should not be invaded.
+Identifiers ending in @code{_t} are reserved by
+@url{http://pubs.opengroup.org/onlinepubs/007904975/functions/xsh_chap02_02.html#tag_02_02_02, POSIX}.
+Also avoid names starting with @code{__} or @code{_} followed by an uppercase
+letter as they are reserved by the C standard. Names starting with @code{_}
+are reserved at the file level and may not be used for externally visible
+symbols. If in doubt, just avoid names starting with @code{_} altogether.
+
 @subsection Miscellaneous conventions
 @itemize @bullet
 @item
@@ -217,8 +229,13 @@ For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:
 
 @enumerate
 @item
-   Contributions should be licensed under the LGPL 2.1, including an
-   "or any later version" clause, or the MIT license.  GPL 2 including
+   Contributions should be licensed under the
+   @uref{http://www.gnu.org/licenses/lgpl-2.1.html, LGPL 2.1},
+   including an "or any later version" clause, or, if you prefer
+   a gift-style license, the
+   @uref{http://www.isc.org/software/license/, ISC} or
+   @uref{http://mit-license.org/, MIT} license.
+   @uref{http://www.gnu.org/licenses/gpl-2.0.html, GPL 2} including
    an "or any later version" clause is also acceptable, but LGPL is
    preferred.
 @item
@@ -341,8 +358,6 @@ For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:
 
 We think our rules are not too hard. If you have comments, contact us.
 
-Note, these rules are mostly borrowed from the MPlayer project.
-
 @anchor{Submitting patches}
 @section Submitting patches