X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=doc%2Fdeveloper.texi;h=32d666ac6829efdbde4a165998703e776185e504;hb=3c5fe5b52758225e58fec917cc29281d6025aa67;hp=29291d0c718d9ae040bba35647429ea7e030fe72;hpb=8709ba907a7f6f44e392161221d9628fa74b22f6;p=ffmpeg diff --git a/doc/developer.texi b/doc/developer.texi index 29291d0c718..32d666ac682 100644 --- a/doc/developer.texi +++ b/doc/developer.texi @@ -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 FFmpeg formatting conventions, paste +the following snippet into your @file{.vimrc}: +@example +" indentation rules for FFmpeg: 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\+\%#\@@