Browse code

doc: document preferred Doxygen syntax and make patcheck detect it

Diego Biurrun authored on 2011/11/08 23:01:47
Showing 2 changed files
... ...
@@ -105,6 +105,11 @@ Use the JavaDoc/Doxygen  format (see examples below) so that code documentation
105 105
 can be generated automatically. All nontrivial functions should have a comment
106 106
 above them explaining what the function does, even if it is just one sentence.
107 107
 All structures and their member variables should be documented, too.
108
+
109
+Avoid Qt-style and similar Doxygen syntax with @code{!} in it, i.e. replace
110
+@code{//!} with @code{///} and similar.  Also @@ syntax should be employed
111
+for markup commands, i.e. use @code{@@param} and not @code{\param}.
112
+
108 113
 @example
109 114
 /**
110 115
  * @@file
... ...
@@ -55,6 +55,7 @@ hiegrep 'INIT_VLC_USE_STATIC' 'forbidden ancient vlc type' $*
55 55
 hiegrep '=[-+\*\&] ' 'looks like compound assignment' $*
56 56
 hiegrep2 '/\*\* *[a-zA-Z0-9].*' '\*/' 'Inconsistently formatted doxygen comment' $*
57 57
 hiegrep '; */\*\*[^<]' 'Misformatted doxygen comment' $*
58
+hiegrep '//!|/\*!' 'inconsistent doxygen syntax' $*
58 59
 
59 60
 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' $*
60 61