1<documentation title="Function Comments">
2    <standard>
3    <![CDATA[
4    Functions must have a non-empty doc comment.  The short description must be on the second line of the comment.  Each description must have one blank comment line before and after.  There must be one blank line before the tags in the comments.  There must be a tag for each of the parameters in the right order with the right variable names with a comment.  There must be a return tag.  Any throw tag must have an exception class.
5    ]]>
6    </standard>
7    <code_comparison>
8        <code title="Valid: A function doc comment is used.">
9        <![CDATA[
10<em>/**
11 * Short description here.
12 *
13 * @return void
14 */</em>
15 function foo()
16 {
17 }
18        ]]>
19        </code>
20        <code title="Invalid: No doc comment for the function.">
21        <![CDATA[
22 function foo()
23 {
24 }
25        ]]>
26        </code>
27    </code_comparison>
28    <code_comparison>
29        <code title="Valid: Short description is the second line of the comment.">
30        <![CDATA[
31/**
32 * <em>Short description here.</em>
33 *
34 * @return void
35 */
36 function foo()
37 {
38 }
39        ]]>
40        </code>
41        <code title="Invalid: An extra blank line before the short description.">
42        <![CDATA[
43/**
44 * <em></em>
45 * <em>Short description here.</em>
46 *
47 * @return void
48 */
49 function foo()
50 {
51 }
52        ]]>
53        </code>
54    </code_comparison>
55    <code_comparison>
56        <code title="Valid: Exactly one blank line around descriptions.">
57        <![CDATA[
58/**
59 * Short description here.
60 * <em></em>
61 * Long description here.
62 * <em></em>
63 * @return void
64 */
65 function foo()
66 {
67 }
68        ]]>
69        </code>
70        <code title="Invalid: Extra blank lines around the descriptions.">
71        <![CDATA[
72/**
73 * Short description here.
74 * <em></em>
75 * <em></em>
76 * Long description here.
77 * <em></em>
78 * <em></em>
79 * @return void
80 */
81 function foo()
82 {
83 }
84        ]]>
85        </code>
86    </code_comparison>
87    <code_comparison>
88        <code title="Valid: Exactly one blank line before the tags.">
89        <![CDATA[
90/**
91 * Short description here.
92 *
93 * Long description here.
94 * <em></em>
95 * @return void
96 */
97 function foo()
98 {
99 }
100        ]]>
101        </code>
102        <code title="Invalid: Extra blank lines before the tags.">
103        <![CDATA[
104/**
105 * Short description here.
106 *
107 * Long description here.
108 * <em></em>
109 * <em></em>
110 * @return void
111 */
112 function foo()
113 {
114 }
115        ]]>
116        </code>
117    </code_comparison>
118    <code_comparison>
119        <code title="Valid: Throws tag has an exception class.">
120        <![CDATA[
121/**
122 * Short description here.
123 *
124 * @return void
125 * @throws <em>FooException</em>
126 */
127 function foo()
128 {
129 }
130        ]]>
131        </code>
132        <code title="Invalid: No exception class given for throws tag.">
133        <![CDATA[
134/**
135 * Short description here.
136 *
137 * @return void
138 * <em>@throws</em>
139 */
140 function foo()
141 {
142 }
143        ]]>
144        </code>
145    </code_comparison>
146    <code_comparison>
147        <code title="Valid: Return tag present.">
148        <![CDATA[
149/**
150 * Short description here.
151 *
152 * <em>@return void</em>
153 */
154 function foo()
155 {
156 }
157        ]]>
158        </code>
159        <code title="Invalid: No return tag.">
160        <![CDATA[
161/**
162 * Short description here.
163 */
164 function foo()
165 {
166 }
167        ]]>
168        </code>
169    </code_comparison>
170    <code_comparison>
171        <code title="Valid: Param names are correct.">
172        <![CDATA[
173/**
174 * Short description here.
175 *
176 * @param string <em>$foo</em> Foo parameter
177 * @param string <em>$bar</em> Bar parameter
178 * @return void
179 */
180 function foo(<em>$foo</em>, <em>$bar</em>)
181 {
182 }
183        ]]>
184        </code>
185        <code title="Invalid: Wrong parameter name doesn't match function signature.">
186        <![CDATA[
187/**
188 * Short description here.
189 *
190 * @param string $foo Foo parameter
191 * @param string <em>$qux</em> Bar parameter
192 * @return void
193 */
194 function foo($foo, <em>$bar</em>)
195 {
196 }
197        ]]>
198        </code>
199    </code_comparison>
200    <code_comparison>
201        <code title="Valid: Param names are ordered correctly.">
202        <![CDATA[
203/**
204 * Short description here.
205 *
206 * @param string <em>$foo</em> Foo parameter
207 * @param string <em>$bar</em> Bar parameter
208 * @return void
209 */
210 function foo(<em>$foo</em>, <em>$bar</em>)
211 {
212 }
213        ]]>
214        </code>
215        <code title="Invalid: Wrong parameter order.">
216        <![CDATA[
217/**
218 * Short description here.
219 *
220 * @param string <em>$bar</em> Bar parameter
221 * @param string <em>$foo</em> Foo parameter
222 * @return void
223 */
224 function foo(<em>$foo</em>, <em>$bar</em>)
225 {
226 }
227        ]]>
228        </code>
229    </code_comparison>
230</documentation>
231