Merge remote-tracking branch 'qatar/master'
[ffmpeg.git] / doc / developer.texi
index 29291d0..59da187 100644 (file)
@@ -38,66 +38,50 @@ to send your patches to the FFmpeg mailing list.
 
 There are 3 ways by which code gets into ffmpeg.
 @itemize @bullet
-@item Submiting Patches to the main developer mailing list
+@item Submitting Patches to the main developer mailing list
       see @ref{Submitting patches} for details.
-@item Directly commiting changes to the main tree.
-@item Commiting changes to a git clone, for example on github.com or
+@item Directly committing changes to the main tree.
+@item Committing changes to a git clone, for example on github.com or
       gitorious.org. And asking us to merge these changes.
 @end itemize
 
 Whichever way, changes should be reviewed by the maintainer of the code
-before they are commited. And they should follow the @ref{Coding Rules}.
+before they are committed. And they should follow the @ref{Coding Rules}.
 The developer making the commit and the author are responsible for their changes
 and should try to fix issues their commit causes.
 
 @anchor{Coding Rules}
 @section Coding Rules
 
-FFmpeg is programmed in the ISO C90 language with a few additional
-features from ISO C99, namely:
-@itemize @bullet
-@item
-the @samp{inline} keyword;
-@item
-@samp{//} comments;
-@item
-designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
-@item
-compound literals (@samp{x = (struct s) @{ 17, 23 @};})
-@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.
+@subsection Code formatting conventions
 
-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;
-@item
-@samp{long long} (use @samp{int64_t} instead);
-@item
-@samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar;
-@item
-GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
-@end itemize
-
 Indent size is 4.
-The presentation is one inspired by 'indent -i4 -kr -nut'.
+@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.
+@item
+You should try to limit your code lines to 80 characters; however, do so if
+and only if this improves readability.
+@end itemize
+The presentation is one inspired by 'indent -i4 -kr -nut'.
 
 The main priority in FFmpeg 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
+@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.
+
+Avoid Qt-style and similar Doxygen syntax with @code{!} in it, i.e. replace
+@code{//!} with @code{///} and similar.  Also @@ syntax should be employed
+for markup commands, i.e. use @code{@@param} and not @code{\param}.
+
 @example
 /**
  * @@file
@@ -128,11 +112,97 @@ int myfunc(int my_parameter)
 ...
 @end example
 
+@subsection C language features
+
+FFmpeg is programmed in the ISO C90 language with a few additional
+features from ISO C99, namely:
+@itemize @bullet
+@item
+the @samp{inline} keyword;
+@item
+@samp{//} comments;
+@item
+designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
+@item
+compound literals (@samp{x = (struct s) @{ 17, 23 @};})
+@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:
+@itemize @bullet
+@item
+mixing statements and declarations;
+@item
+@samp{long long} (use @samp{int64_t} instead);
+@item
+@samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar;
+@item
+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
+for example structs and enums; they should always be in the CamelCase
+
+
+There are 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.
+@item
+For variables and functions used internally by the library, @code{ff_} prefix
+should be used.
+For example, @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.
+@end itemize
+
+@subsection Miscellanous conventions
+@itemize @bullet
+@item
 fprintf and printf are forbidden in libavformat and libavcodec,
 please use av_log() instead.
-
+@item
 Casts should be used only when necessary. Unneeded parentheses
 should also be avoided if they don't make the code easier to understand.
+@end itemize
+
+@subsection Editor configuration
+In order to configure Vim to follow Libav formatting conventions, paste
+the following snippet into your @file{.vimrc}:
+@example
+" indentation rules for libav: 4 spaces, no tabs
+set expandtab
+set shiftwidth=4
+set softtabstop=4
+" allow tabs in Makefiles
+autocmd FileType make set noexpandtab shiftwidth=8 softtabstop=8
+" Trailing whitespace and tabs are forbidden, so highlight them.
+highlight ForbiddenWhitespace ctermbg=red guibg=red
+match ForbiddenWhitespace /\s\+$\|\t/
+" Do not highlight spaces at the end of line while typing on that line.
+autocmd InsertEnter * match ForbiddenWhitespace /\t\|\s\+\%#\@@<!$/
+@end example
+
+For Emacs, add these roughly equivalent lines to your @file{.emacs.d/init.el}:
+@example
+(setq c-default-style "k&r")
+(setq-default c-basic-offset 4)
+(setq-default indent-tabs-mode nil)
+(setq-default show-trailing-whitespace t)
+@end example
 
 @section Development Policy
 
@@ -194,7 +264,7 @@ should also be avoided if they don't make the code easier to understand.
    Always fill out the commit log message. Describe in a few lines what you
    changed and why. You can refer to mailing list postings if you fix a
    particular bug. Comments such as "fixed!" or "Changed it." are unacceptable.
-   Recommanded format:
+   Recommended format:
    area changed: Short 1 line description
 
    details describing what and why and giving references.
@@ -316,7 +386,7 @@ send a reminder by email. Your patch should eventually be dealt with.
 @item
     Did you add the CodecID to @file{avcodec.h}?
 @item
-    If it has a fourcc, did you add it to @file{libavformat/riff.c},
+    If it has a fourCC, did you add it to @file{libavformat/riff.c},
     even if it is only a decoder?
 @item
     Did you add a rule to compile the appropriate files in the Makefile?
@@ -435,7 +505,7 @@ where its best maintained.
 
 When resubmitting patches, please do not make any significant changes
 not related to the comments received during review. Such patches will
-be rejected. Instead, submit  significant changes or new features as
+be rejected. Instead, submit significant changes or new features as
 separate patches.
 
 @section Regression tests