-
-
Notifications
You must be signed in to change notification settings - Fork 89
[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.
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
jrfnl
merged 16 commits into
PHPCSStandards:master
from
costdev:docs/Squiz.Commenting.BlockComment
Mar 23, 2025
Merged
Changes from 14 commits
Commits
Show all changes
16 commits
Select commit
Hold shift + click to select a range
576382c
Add documentation for Squiz.Commenting.BlockComment.
costdev c0747c7
Apply suggestions from code review
costdev e122f81
Add a short description of a block comment.
costdev 5d1a3dc
Improve opener/closer descriptions and comparisons.
costdev cb43ef7
Merge `HasEmptyLine` and `NoNewLine` entries.
costdev 22d0415
Add guidance for `LastLineIndent`.
costdev 53402a5
Make `SingleLine` guidance second.
costdev e66d021
Make `Empty` guidance third.
costdev 3823a4a
Make `HasEmptyLine`/`NoNewLine` guidance fourth.
costdev 3e97c09
Make `NoCapital` guidance seventh.
costdev 7b75bd1
Make `LastLineIndent` guidance ninth.
costdev fd0b00d
Clarify that "open tag" means "PHP open tag".
costdev 2280060
Improve `<em></em>` usage.
costdev 3e6fe45
End the file on a new line.
costdev 4e45f1b
Suggested text change to the first standard.
costdev 98dc960
Use `multi-line` instead of `multiline`.
costdev File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
280 changes: 280 additions & 0 deletions
280
src/Standards/Squiz/Docs/Commenting/BlockCommentStandard.xml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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 multiline comment delimited by an opener "/*" and a closer "*/" which are each on their own line and the content is 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> | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just checking: is it "multiline" or "multi-line" ? Whichever it should be, let's use it consistently (here versus line 48 of the docs "Valid: Multi-line block comment").
Also, how about this ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
From what I can see, UK English uses multi-line, US English doesn't.
Which would you prefer?
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I prefer consistency, whether it is the one or the other ;-)
I know there are some typical words which are written differently in US vs UK English - "modernize" vs "modernise" comes to mind.
Might be worth checking the code base/docs to see what's mostly used, US or UK English, though I'm not sure if this was strictly adhered to in the past anyhow.
If a spot check shows a mix of both, I suggest we open an issue to choose one and make the docs consistently use that language variant (as a separate task, outside the scope of this PR).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Checking a small number of differences, such as
multi-linevsmultiline,isevsize,colourvscolor, and such shows a mixture in the repository. Some spellings occur more in comments, others in docs, others in code, and others differ across three of those areas. Obviouslycolor/background-colorin CSS doesn't count, but for example, there'sNamedColourSniffandT_COLOUR, but also theprivate colorizeVariableInput()method in the Help utility class.Regarding this PR, it looks like
multi-lineis used more often outside of things like PHP class names where the hyphen isn't an option. I'll update the PR to usemulti-lineconsistently. At least it'll make it easier to change in one go should the variant of English be changed in the future.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for checking that @costdev. I'm not too concerned about the CSS sniff/tokens as those will be removed soon anyway, but I think opening an issue about language consistency might be a good idea. Want to do the honours ?