[FFmpeg-cvslog] Update developers documentation with coding conventions.

[Victor Vasiliev]

ffmpeg | branch: master | Victor Vasiliev <vasilvv at gmail.com> | Thu Dec  1 20:45:44 2011 +0400| [9b9815eec4231d9efea7cd5c6a18c09c2ebff310] | committer: Luca Barbato

Update developers documentation with coding conventions.

Signed-off-by: Luca Barbato <lu_zero at gentoo.org>

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

 doc/developer.texi |  123 +++++++++++++++++++++++++++++++++++++++++-----------
 1 files changed, 97 insertions(+), 26 deletions(-)

diff --git a/doc/developer.texi b/doc/developer.texi
index 800009e..128b46e 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -45,48 +45,61 @@ mailing list.
 @anchor{Coding Rules}
 @section Coding Rules
 
-Libav is programmed in the ISO C90 language with a few additional
-features from ISO C99, namely:
+ at subsection Code formatting conventions
+The code is written in K&R C style. That means the following:
 @itemize @bullet
 @item
-the @samp{inline} keyword;
+The control statements are formatted by putting space betwen the statement and parenthesis
+in the following way:
+ at example
+for (i = 0; i < filter->input_count; i ++) @{
+ at end example
 @item
- at samp{//} comments;
+The case statement is always located at the same level as the switch itself:
+ at example
+switch (link->init_state) @{
+case AVLINK_INIT:
+    continue;
+case AVLINK_STARTINIT:
+    av_log(filter, AV_LOG_INFO, "circular filter chain detected");
+    return 0;
+ at end example
 @item
-designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
+Braces in function declarations are written on the new line:
+ at example
+const char *avfilter_configuration(void)
+@{
+    return LIBAV_CONFIGURATION;
+@}
+ at end example
 @item
-compound literals (@samp{x = (struct s) @{ 17, 23 @};})
+In case of a single-statement if, no curly braces are required:
+ at example
+if (!pic || !picref)
+    goto fail;
+ at end example
+ at item
+Do not put spaces immediately inside parenthesis. @samp{if (ret)} is a valid style; @samp{if ( ret )} is not.
 @end itemize
 
-These features are supported by all compilers we care about, so we will not
-accept patches to remove their use unless they absolutely do not impair
-clarity and performance.
-
-All code must compile with recent versions of GCC and a number of other
-currently supported compilers. To ensure compatibility, please do not use
-additional C99 features or GCC extensions. Especially watch out for:
+There are the following guidelines regarding the indentation in files:
 @itemize @bullet
 @item
-mixing statements and declarations;
- at item
- at samp{long long} (use @samp{int64_t} instead);
- at item
- at samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar;
- at item
-GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
- at end itemize
-
 Indent size is 4.
-The presentation is one inspired by 'indent -i4 -kr -nut'.
+ at item
 The TAB character is forbidden outside of Makefiles as is any
 form of trailing whitespace. Commits containing either will be
 rejected by the git repository.
+ at item
+You should try to limit your code lines to 80 characters; however, do so if and only if this improves readability.
+ at end itemize
+The presentation is one inspired by 'indent -i4 -kr -nut'.
 
 The main priority in Libav is simplicity and small code size in order to
 minimize the bug count.
 
-Comments: Use the JavaDoc/Doxygen
-format (see examples below) so that code documentation
+ at subsection Comments
+Use the JavaDoc/Doxygen  format (see examples below) so that code documentation
 can be generated automatically. All nontrivial functions should have a comment
 above them explaining what the function does, even if it is just one sentence.
 All structures and their member variables should be documented, too.
@@ -120,11 +133,69 @@ int myfunc(int my_parameter)
 ...
 @end example
 
+ at subsection C language features
+
+Libav is programmed in the ISO C90 language with a few additional
+features from ISO C99, namely:
+ at itemize @bullet
+ at item
+the @samp{inline} keyword;
+ at item
+ at samp{//} comments;
+ at item
+designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
+ at item
+compound literals (@samp{x = (struct s) @{ 17, 23 @};})
+ at end itemize
+
+These features are supported by all compilers we care about, so we will not
+accept patches to remove their use unless they absolutely do not impair
+clarity and performance.
+
+All code must compile with recent versions of GCC and a number of other
+currently supported compilers. To ensure compatibility, please do not use
+additional C99 features or GCC extensions. Especially watch out for:
+ at itemize @bullet
+ at item
+mixing statements and declarations;
+ at item
+ at samp{long long} (use @samp{int64_t} instead);
+ at item
+ at samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar;
+ at item
+GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
+ at end itemize
+
+ at 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 only exception from this are structure names;
+they should always be in the CamelCase
+
+There are following conventions for naming variables and functions:
+ at itemize @bullet
+ at item
+For local variables no prefix is required.
+ at item
+For variables and functions declared as @code{static} no prefixes are required.
+ at item
+For variables and functions used internally by the library, @code{ff_} prefix should be used.
+For example, @samp{ff_w64_demuxer}.
+ at item
+For variables and functions used internally across multiple libraries, use @code{avpriv_}. For example,
+ at samp{avpriv_aac_parse_header}.
+ at item
+For exported names, each library has its own prefixes. Just check the existing code and name accordingly.
+ at end itemize
+
+ at subsection Miscellanous conventions
+ at itemize @bullet
+ at item
 fprintf and printf are forbidden in libavformat and libavcodec,
 please use av_log() instead.
-
+ at item
 Casts should be used only when necessary. Unneeded parentheses
 should also be avoided if they don't make the code easier to understand.
+ at end itemize
 
 @section Development Policy