Skip to content

Commit 79238b1

Browse files
costdevcostdev
authored
[Docs] Add XML doc for Squiz.Commenting.BlockComment sniff (#848)
1 parent a4c38a9 commit 79238b1

File tree

1 file changed

+280
-0
lines changed

1 file changed

+280
-0
lines changed

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

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

0 commit comments

Comments
 (0)