1<documentation title="File Comments">
2    <standard>
3    <![CDATA[
4    Files 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 category, package, author, license, and link tag.  There may only be one category, package, subpackage, license, version, since and deprecated tag.  The tags must be in the order category, package, subpackage, author, copyright, license, version, link, see, since, and deprecated.  The php version must be specified.
5    ]]>
6    </standard>
7    <code_comparison>
8        <code title="Valid: A file comment is used.">
9        <![CDATA[
10<?php
11<em>/**
12 * Short description here.
13 *
14 * PHP version 5
15 *
16 * @category Foo
17 * @package Foo_Helpers
18 * @author Marty McFly <mmcfly@example.com>
19 * @copyright 2013-2014 Foo Inc.
20 * @license MIT License
21 * @link http://example.com
22 */</em>
23        ]]>
24        </code>
25        <code title="Invalid: No doc comment for the class.">
26        <![CDATA[
27<?php
28<em></em>
29        ]]>
30        </code>
31    </code_comparison>
32    <code_comparison>
33        <code title="Valid: Short description is the second line of the comment.">
34        <![CDATA[
35<?php
36/**
37 * <em>Short description here.</em>
38 *
39 * PHP version 5
40 *
41 * @category Foo
42 * @package Foo_Helpers
43 * @author Marty McFly <mmcfly@example.com>
44 * @copyright 2013-2014 Foo Inc.
45 * @license MIT License
46 * @link http://example.com
47 */
48        ]]>
49        </code>
50        <code title="Invalid: An extra blank line before the short description.">
51        <![CDATA[
52<?php
53/**
54 * <em></em>
55 * <em>Short description here.</em>
56 *
57 * PHP version 5
58 *
59 * @category Foo
60 * @package Foo_Helpers
61 * @author Marty McFly <mmcfly@example.com>
62 * @copyright 2013-2014 Foo Inc.
63 * @license MIT License
64 * @link http://example.com
65 */
66        ]]>
67        </code>
68    </code_comparison>
69    <code_comparison>
70        <code title="Valid: Exactly one blank line around descriptions.">
71        <![CDATA[
72<?php
73/**
74 * Short description here.
75 * <em></em>
76 * PHP version 5
77 * <em></em>
78 * @category Foo
79 * @package Foo_Helpers
80 * @author Marty McFly <mmcfly@example.com>
81 * @copyright 2013-2014 Foo Inc.
82 * @license MIT License
83 * @link http://example.com
84 */
85        ]]>
86        </code>
87        <code title="Invalid: Extra blank lines around the descriptions.">
88        <![CDATA[
89<?php
90/**
91 * Short description here.
92 * <em></em>
93 * <em></em>
94 * PHP version 5
95 * <em></em>
96 * <em></em>
97 * @category Foo
98 * @package Foo_Helpers
99 * @author Marty McFly <mmcfly@example.com>
100 * @copyright 2013-2014 Foo Inc.
101 * @license MIT License
102 * @link http://example.com
103 */
104        ]]>
105        </code>
106    </code_comparison>
107    <code_comparison>
108        <code title="Valid: Exactly one blank line before the tags.">
109        <![CDATA[
110<?php
111/**
112 * Short description here.
113 *
114 * PHP version 5
115 * <em></em>
116 * @category Foo
117 * @package Foo_Helpers
118 * @author Marty McFly <mmcfly@example.com>
119 * @copyright 2013-2014 Foo Inc.
120 * @license MIT License
121 * @link http://example.com
122 */
123        ]]>
124        </code>
125        <code title="Invalid: Extra blank lines before the tags.">
126        <![CDATA[
127<?php
128/**
129 * Short description here.
130 *
131 * PHP version 5
132 * <em></em>
133 * <em></em>
134 * @category Foo
135 * @package Foo_Helpers
136 * @author Marty McFly <mmcfly@example.com>
137 * @copyright 2013-2014 Foo Inc.
138 * @license MIT License
139 * @link http://example.com
140 */
141        ]]>
142        </code>
143    </code_comparison>
144    <code_comparison>
145        <code title="Valid: All required tags are used.">
146        <![CDATA[
147<?php
148/**
149 * Short description here.
150 *
151 * PHP version 5
152 *
153 * <em>@category</em> Foo
154 * <em>@package</em> Foo_Helpers
155 * <em>@author</em> Marty McFly <mmcfly@example.com>
156 * <em>@copyright</em> 2013-2014 Foo Inc.
157 * <em>@license</em> MIT License
158 * <em>@link</em> http://example.com
159 */
160        ]]>
161        </code>
162        <code title="Invalid: Missing an author tag.">
163        <![CDATA[
164<?php
165/**
166 * Short description here.
167 *
168 * PHP version 5
169 *
170 * @category Foo
171 * @package Foo_Helpers
172 * @copyright 2013-2014 Foo Inc.
173 * @license MIT License
174 * @link http://example.com
175 */
176        ]]>
177        </code>
178    </code_comparison>
179    <code_comparison>
180        <code title="Valid: Tags that should only be used once are only used once.">
181        <![CDATA[
182<?php
183/**
184 * Short description here.
185 *
186 * PHP version 5
187 *
188 * <em>@category</em> Foo
189 * <em>@package</em> Foo_Helpers
190 * @author Marty McFly <mmcfly@example.com>
191 * @copyright 2013-2014 Foo Inc.
192 * <em>@license</em> MIT License
193 * @link http://example.com
194 */
195        ]]>
196        </code>
197        <code title="Invalid: Multiple category tags.">
198        <![CDATA[
199<?php
200/**
201 * Short description here.
202 *
203 * PHP version 5
204 *
205 * <em>@category</em> Foo
206 * <em>@category</em> Bar
207 * @package Foo_Helpers
208 * @author Marty McFly <mmcfly@example.com>
209 * @copyright 2013-2014 Foo Inc.
210 * @license MIT License
211 * @link http://example.com
212 */
213        ]]>
214        </code>
215    </code_comparison>
216    <code_comparison>
217        <code title="Valid: PHP version specified.">
218        <![CDATA[
219<?php
220/**
221 * Short description here.
222 *
223 * <em>PHP version 5</em>
224 *
225 * @category Foo
226 * @package Foo_Helpers
227 * @author Marty McFly <mmcfly@example.com>
228 * @copyright 2013-2014 Foo Inc.
229 * @license MIT License
230 * @link http://example.com
231 */
232        ]]>
233        </code>
234        <code title="Invalid: Category and package tags are swapped in order.">
235        <![CDATA[
236<?php
237/**
238 * Short description here.
239 *
240 * PHP version 5
241 *
242 * <em>@package</em> Foo_Helpers
243 * <em>@category</em> Foo
244 * @author Marty McFly <mmcfly@example.com>
245 * @copyright 2013-2014 Foo Inc.
246 * @license MIT License
247 * @link http://example.com
248 */
249        ]]>
250        </code>
251    </code_comparison>
252    <code_comparison>
253        <code title="Valid: Tags are in the correct order.">
254        <![CDATA[
255<?php
256/**
257 * Short description here.
258 *
259 * PHP version 5
260 *
261 * @category Foo
262 * @package Foo_Helpers
263 * @author Marty McFly <mmcfly@example.com>
264 * @copyright 2013-2014 Foo Inc.
265 * @license MIT License
266 * @link http://example.com
267 */
268        ]]>
269        </code>
270        <code title="Invalid: No php version specified.">
271        <![CDATA[
272<?php
273/**
274 * Short description here.
275 *
276 * @category Foo
277 * @package Foo_Helpers
278 * @author Marty McFly <mmcfly@example.com>
279 * @copyright 2013-2014 Foo Inc.
280 * @license MIT License
281 * @link http://example.com
282 */
283        ]]>
284        </code>
285    </code_comparison>
286</documentation>
287