diff options
| author | Diego Biurrun | 2011-11-08 15:01:47 +0100 |
|---|---|---|
| committer | Diego Biurrun | 2011-12-04 23:49:48 +0100 |
| commit | def5dc1260e99cf7f6e99747013307a152bed801 (patch) | |
| tree | 8d224bc04671025cace22f68324605154bc7463f | |
| parent | dc6d0430503ecd7ed0d81276f977b26b4c4bd916 (diff) | |
doc: document preferred Doxygen syntax and make patcheck detect it
| -rw-r--r-- | doc/developer.texi | 5 | ||||
| -rwxr-xr-x | tools/patcheck | 1 |
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' $* |