Skip to content

Commit 576382c

Browse files
costdevcostdev
committed
Add documentation for Squiz.Commenting.BlockComment.
1 parent bf2b64d commit 576382c

File tree

1 file changed

+316
-0
lines changed

1 file changed

+316
-0
lines changed

‎src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml‎

Lines changed: 316 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,316 @@
1+
<documentation title="Block Comment">
2+
<standard>
3+
<![CDATA[
4+
A block comment should use /* */.
5+
]]>
6+
</standard>
7+
<code_comparison>
8+
<code title="Valid: Uses /* */.">
9+
<![CDATA[
10+
/*
11+
A block comment.
12+
*/
13+
]]>
14+
</code>
15+
<code title="Invalid: Uses /** */.">
16+
<![CDATA[
17+
<em>/**</em>
18+
A block comment.
19+
*/
20+
]]>
21+
</code>
22+
</code_comparison>
23+
<code_comparison>
24+
<code title="Valid: Uses /* */.">
25+
<![CDATA[
26+
/*
27+
A block comment.
28+
*/
29+
]]>
30+
</code>
31+
<code title="Invalid: Uses /* **/.">
32+
<![CDATA[
33+
/*
34+
A block comment.
35+
<em>**/</em>
36+
]]>
37+
</code>
38+
</code_comparison>
39+
<code_comparison>
40+
<code title="Valid: Uses /* */.">
41+
<![CDATA[
42+
/*
43+
A block comment.
44+
*/
45+
]]>
46+
</code>
47+
<code title="Invalid: Uses /** **/.">
48+
<![CDATA[
49+
<em>/**</em>
50+
A block comment.
51+
<em>**/</em>
52+
]]>
53+
</code>
54+
</code_comparison>
55+
<code_comparison>
56+
<code title="Valid: Uses /* */.">
57+
<![CDATA[
58+
/*
59+
A block comment
60+
with
61+
multiple lines.
62+
*/
63+
]]>
64+
</code>
65+
<code title="Invalid: Uses multiple //.">
66+
<![CDATA[
67+
<em>//</em> A block comment
68+
<em>//</em> with
69+
<em>//</em> multiple lines.
70+
]]>
71+
</code>
72+
</code_comparison>
73+
<code_comparison>
74+
<code title="Valid: Uses /* */.">
75+
<![CDATA[
76+
/*
77+
A block comment
78+
with
79+
multiple lines.
80+
*/
81+
]]>
82+
</code>
83+
<code title="Invalid: Uses multiple #.">
84+
<![CDATA[
85+
<em>#</em> A block comment
86+
<em>#</em> with
87+
<em>#</em> multiple lines.
88+
]]>
89+
</code>
90+
</code_comparison>
91+
<standard>
92+
<![CDATA[
93+
If asterisks are not used, the contents should be indented by at least 4 spaces.
94+
]]>
95+
</standard>
96+
<code_comparison>
97+
<code title="Valid: Indented by at least 4 spaces.">
98+
<![CDATA[
99+
/*
100+
A block comment
101+
with
102+
multiple lines.
103+
*/
104+
]]>
105+
</code>
106+
<code title="Invalid: Indented by less than 4 spaces.">
107+
<![CDATA[
108+
/*
109+
<em> </em>A block comment
110+
<em> </em>with
111+
<em> </em>multiple lines.
112+
*/
113+
]]>
114+
</code>
115+
</code_comparison>
116+
<standard>
117+
<![CDATA[
118+
If asterisks are used, they should be aligned.
119+
]]>
120+
</standard>
121+
<code_comparison>
122+
<code title="Valid: Asterisks are aligned.">
123+
<![CDATA[
124+
/*
125+
* A block comment
126+
* with
127+
* multiple lines.
128+
*/
129+
]]>
130+
</code>
131+
<code title="Invalid: Asterisks are not aligned.">
132+
<![CDATA[
133+
/*
134+
* A block comment
135+
<em>* with</em>
136+
* multiple lines.
137+
<em>*/</em>
138+
]]>
139+
</code>
140+
</code_comparison>
141+
<standard>
142+
<![CDATA[
143+
A block comment should not be empty.
144+
]]>
145+
</standard>
146+
<code_comparison>
147+
<code title="Valid: A block comment with contents.">
148+
<![CDATA[
149+
/*
150+
A block comment.
151+
*/
152+
]]>
153+
</code>
154+
<code title="Invalid: An empty block comment.">
155+
<![CDATA[
156+
/*
157+
<em></em>
158+
*/
159+
]]>
160+
</code>
161+
</code_comparison>
162+
<standard>
163+
<![CDATA[
164+
Single line block comments are not allowed.
165+
]]>
166+
</standard>
167+
<code_comparison>
168+
<code title="Valid: Uses multiple lines.">
169+
<![CDATA[
170+
/*
171+
A block comment.
172+
*/
173+
]]>
174+
</code>
175+
<code title="Invalid: Uses a single line.">
176+
<![CDATA[
177+
<em>/* A block comment. */</em>
178+
]]>
179+
</code>
180+
</code_comparison>
181+
<standard>
182+
<![CDATA[
183+
Block comment text should start on a new line.
184+
]]>
185+
</standard>
186+
<code_comparison>
187+
<code title="Valid: Text starts on a new line.">
188+
<![CDATA[
189+
/*
190+
A block comment.
191+
*/
192+
]]>
193+
</code>
194+
<code title="Invalid: Text starts on the same line.">
195+
<![CDATA[
196+
/* <em>A block comment.</em>
197+
*/
198+
]]>
199+
</code>
200+
</code_comparison>
201+
<standard>
202+
<![CDATA[
203+
The block comment closer should be on a new line.
204+
]]>
205+
</standard>
206+
<code_comparison>
207+
<code title="Valid: Closer is on a new line.">
208+
<![CDATA[
209+
/*
210+
A block comment.
211+
*/
212+
]]>
213+
</code>
214+
<code title="Invalid: Closer is not on a new line.">
215+
<![CDATA[
216+
/*
217+
<em>A block comment. */</em>
218+
]]>
219+
</code>
220+
</code_comparison>
221+
<standard>
222+
<![CDATA[
223+
The first line should not be empty.
224+
]]>
225+
</standard>
226+
<code_comparison>
227+
<code title="Valid: The first line is not empty.">
228+
<![CDATA[
229+
/*
230+
A block comment.
231+
*/
232+
]]>
233+
</code>
234+
<code title="Invalid: The first line is empty.">
235+
<![CDATA[
236+
/*
237+
<em></em>
238+
A block comment.
239+
*/
240+
]]>
241+
</code>
242+
</code_comparison>
243+
<standard>
244+
<![CDATA[
245+
There should be an empty line after the block comment.
246+
]]>
247+
</standard>
248+
<code_comparison>
249+
<code title="Valid: An empty line after the comment.">
250+
<![CDATA[
251+
/*
252+
A block comment.
253+
*/
254+
255+
echo 'Content';
256+
]]>
257+
</code>
258+
<code title="Invalid: No empty line after the comment.">
259+
<![CDATA[
260+
/*
261+
A block comment.
262+
*/
263+
<em>echo 'Content';</em>
264+
]]>
265+
</code>
266+
</code_comparison>
267+
<standard>
268+
<![CDATA[
269+
A block comment should start with a capital letter.
270+
]]>
271+
</standard>
272+
<code_comparison>
273+
<code title="Valid: Starts with a capital letter.">
274+
<![CDATA[
275+
/*
276+
A block comment.
277+
*/
278+
]]>
279+
</code>
280+
<code title="Invalid: Does not start with a capital letter.">
281+
<![CDATA[
282+
/*
283+
<em>a</em> block comment.
284+
*/
285+
]]>
286+
</code>
287+
</code_comparison>
288+
<standard>
289+
<![CDATA[
290+
A block comment immediately after an open tag should not have a preceeding blank line.
291+
]]>
292+
</standard>
293+
<code_comparison>
294+
<code title="Valid: No blank line after an open tag.">
295+
<![CDATA[
296+
<?php
297+
/*
298+
* A block comment
299+
* with
300+
* multiple lines.
301+
*/
302+
]]>
303+
</code>
304+
<code title="Invalid: A blank line after an open tag.">
305+
<![CDATA[
306+
<?php
307+
<em></em>
308+
/*
309+
* A block comment
310+
* with
311+
* multiple lines.
312+
*/
313+
]]>
314+
</code>
315+
</code_comparison>
316+
</documentation>

0 commit comments

Comments
 (0)