aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDiego Biurrun <diego@biurrun.de>2011-11-08 15:01:47 +0100
committerDiego Biurrun <diego@biurrun.de>2011-12-04 23:49:48 +0100
commitdef5dc1260e99cf7f6e99747013307a152bed801 (patch)
tree8d224bc04671025cace22f68324605154bc7463f
parentdc6d0430503ecd7ed0d81276f977b26b4c4bd916 (diff)
downloadffmpeg-def5dc1260e99cf7f6e99747013307a152bed801.tar.gz
doc: document preferred Doxygen syntax and make patcheck detect it
-rw-r--r--doc/developer.texi5
-rwxr-xr-xtools/patcheck1
2 files changed, 6 insertions, 0 deletions
diff --git a/doc/developer.texi b/doc/developer.texi
index a63bea746c..c9cf7bde98 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -105,6 +105,11 @@ 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
diff --git a/tools/patcheck b/tools/patcheck
index 19faf47b1d..285496d6e6 100755
--- a/tools/patcheck
+++ b/tools/patcheck
@@ -55,6 +55,7 @@ hiegrep 'INIT_VLC_USE_STATIC' 'forbidden ancient vlc type' $*
hiegrep '=[-+\*\&] ' 'looks like compound assignment' $*
hiegrep2 '/\*\* *[a-zA-Z0-9].*' '\*/' 'Inconsistently formatted doxygen comment' $*
hiegrep '; */\*\*[^<]' 'Misformatted doxygen comment' $*
+hiegrep '//!|/\*!' 'inconsistent doxygen syntax' $*
hiegrep2 '(int|unsigned|static|void)[a-zA-Z0-9 _]*(init|end)[a-zA-Z0-9 _]*\(.*[^;]$' '(av_cold|:\+[^a-zA-Z_])' 'These functions may need av_cold, please review the whole patch for similar functions needing av_cold' $*