Skip to content

[Docs] Add XML doc for Squiz.Commenting.BlockComment sniff #848

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Mar 23, 2025
Merged

[Docs] Add XML doc for Squiz.Commenting.BlockComment sniff #848

Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
576382c
Add documentation for Squiz.Commenting.BlockComment.
costdev Feb 27, 2025
c0747c7
Apply suggestions from code review
costdev Mar 8, 2025
e122f81
Add a short description of a block comment.
costdev Mar 16, 2025
5d1a3dc
Improve opener/closer descriptions and comparisons.
costdev Mar 16, 2025
cb43ef7
Merge `HasEmptyLine` and `NoNewLine` entries.
costdev Mar 16, 2025
22d0415
Add guidance for `LastLineIndent`.
costdev Mar 16, 2025
53402a5
Make `SingleLine` guidance second.
costdev Mar 16, 2025
e66d021
Make `Empty` guidance third.
costdev Mar 16, 2025
3823a4a
Make `HasEmptyLine`/`NoNewLine` guidance fourth.
costdev Mar 16, 2025
3e97c09
Make `NoCapital` guidance seventh.
costdev Mar 16, 2025
7b75bd1
Make `LastLineIndent` guidance ninth.
costdev Mar 16, 2025
fd0b00d
Clarify that "open tag" means "PHP open tag".
costdev Mar 16, 2025
2280060
Improve `<em></em>` usage.
costdev Mar 16, 2025
3e6fe45
End the file on a new line.
costdev Mar 20, 2025
4e45f1b
Suggested text change to the first standard.
costdev Mar 23, 2025
98dc960
Use `multi-line` instead of `multiline`.
costdev Mar 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
280 changes: 280 additions & 0 deletions src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,280 @@
<documentation title="Block Comment">
<standard>
<![CDATA[
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.
]]>
</standard>
<code_comparison>
<code title="Valid: Uses a valid opener and closer.">
<![CDATA[
<em>/*</em>
A block comment.
<em>*/</em>
]]>
</code>
<code title="Invalid: Uses /** **/.">
<![CDATA[
<em>/**</em>
A block comment.
<em>**/</em>
]]>
</code>
</code_comparison>
<code_comparison>
<code title="Valid: Uses a valid opener and closer.">
<![CDATA[
<em>/*</em>
* A block comment
* with multiple lines.
<em>*/</em>
]]>
</code>
<code title="Invalid: Uses multiple // or #.">
<![CDATA[
<em>//</em> A block comment
<em>//</em> with multiple lines.

<em>#</em> A block comment
<em>#</em> with multiple lines.
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
Single line block comments are not allowed.
]]>
</standard>
<code_comparison>
<code title="Valid: Multi-line block comment.">
<![CDATA[
<em>/*
A block comment.
*/</em>
]]>
</code>
<code title="Invalid: Single line block comment.">
<![CDATA[
<em>/* A block comment. */</em>
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
A block comment should not be empty.
]]>
</standard>
<code_comparison>
<code title="Valid: A block comment with contents.">
<![CDATA[
/*
<em> A block comment.</em>
*/
]]>
</code>
<code title="Invalid: An empty block comment.">
<![CDATA[
/*
<em></em>
*/
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
Block comment text should start on a new line immediately after the opener.
]]>
</standard>
<code_comparison>
<code title="Valid: Text starts on a new line.">
<![CDATA[
/*
<em> A block comment.</em>
*/
]]>
</code>
<code title="Invalid: Text starts on the same line.">
<![CDATA[
/* <em>A block comment.</em>
*/
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
If there are no asterisks at the start of each line, the contents of the docblock should be indented by at least 4 spaces.
]]>
</standard>
<code_comparison>
<code title="Valid: Indented by at least 4 spaces.">
<![CDATA[
/*
<em> </em>A block comment
<em> </em>with multiple lines.
<em> </em>And a second paragraph.
*/
]]>
</code>
<code title="Invalid: Indented by less than 4 spaces.">
<![CDATA[
/*
<em> </em>A block comment
<em> </em>with
<em> </em>multiple lines.
*/
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
If asterisks are used, they should be aligned.
]]>
</standard>
<code_comparison>
<code title="Valid: Asterisks are aligned.">
<![CDATA[
/<em>*</em>
<em>*</em> A block comment
<em>*</em> with
<em>*</em> multiple lines.
<em>*</em>/
]]>
</code>
<code title="Invalid: Asterisks are not aligned.">
<![CDATA[
/*
* A block comment
<em>*</em> with
* multiple lines.
<em>*</em>/
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
A block comment should start with a capital letter.
]]>
</standard>
<code_comparison>
<code title="Valid: Starts with a capital letter.">
<![CDATA[
/*
<em>A</em> block comment.
*/
]]>
</code>
<code title="Invalid: Does not start with a capital letter.">
<![CDATA[
/*
<em>a</em> block comment.
*/
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
The block comment closer should be on a new line.
]]>
</standard>
<code_comparison>
<code title="Valid: Closer is on a new line.">
<![CDATA[
/*
A block comment.
<em>*/</em>
]]>
</code>
<code title="Invalid: Closer is not on a new line.">
<![CDATA[
/*
A block comment.<em> */</em>
]]>
</code>
</code_comparison>
<standard>
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.
</standard>
<code_comparison>
<code title="Valid: The closer's asterisk is aligned with other asterisks.">
<![CDATA[
/<em>*</em>
<em>*</em> A block comment
<em>*</em>/
]]>
</code>
<code title="Invalid: The closer's asterisk is not aligned with other asterisks.">
<![CDATA[
/*
* A block comment.
<em>*</em>/
]]>
</code>
</code_comparison>
<code_comparison>
<code title="Valid: The closer's asterisk is aligned with the opener's slash.">
<![CDATA[
<em>/</em>*
A block comment.
<em>*</em>/
]]>
</code>
<code title="Invalid: The closer's asterisk is not aligned with the opener's slash.">
<![CDATA[
/*
A block comment.
<em> *</em>/
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
There should be an empty line after the block comment.
]]>
</standard>
<code_comparison>
<code title="Valid: An empty line after the comment.">
<![CDATA[
/*
A block comment.
*/
<em></em>
echo 'Content';
]]>
</code>
<code title="Invalid: No empty line after the comment.">
<![CDATA[
/*
A block comment.
*/
<em>echo 'Content';</em>
]]>
</code>
</code_comparison>
<standard>
<![CDATA[
A block comment immediately after a PHP open tag should not have a preceeding blank line.
]]>
</standard>
<code_comparison>
<code title="Valid: No blank line after an open tag.">
<![CDATA[
<?php
<em></em>/*
* A block comment
* with
* multiple lines.
*/
]]>
</code>
<code title="Invalid: A blank line after an open tag.">
<![CDATA[
<?php
<em></em>
/*
* A block comment
* with
* multiple lines.
*/
]]>
</code>
</code_comparison>
</documentation>