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

[costdev]

Description

Adds XML doc for the Squiz\Commenting\BlockComment sniff.

Suggested changelog entry

Add XML doc for Squiz.Commenting.BlockComment sniff

Related issues/external references

Partial fix for #148

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
  • This change is only breaking for integrators, not for external standards or end-users.
• Documentation improvement

PR checklist

• I have checked there is no other PR open for the same change.
• I have read the Contribution Guidelines.
• I grant the project the right to include and distribute the code under the BSD-3-Clause license (and I have the right to grant these rights).
• I have added tests to cover my changes.
• I have verified that the code complies with the projects coding standards.
• [Required for new sniffs] I have added XML documentation for the sniff.

[jrfnl]

Hi @costdev Welcome and thank you for your willingness to contribute to PHP_CodeSniffer!

I love the effort you've put into this one. Having said that, the doc is quite large now, which makes me wonder if it would be possible to convey the same information in a slightly more succinct manner to improve the chances of it actually getting read 😉

Here are some suggestions to consider, but please think it over yourself and feel free to deviate:

• What about including a short description of what is considered a "block comment" in the first <standard> block ?
• First <standard> has five code comparisons - could the same information be conveyed in maybe two code comparisons ?
  And maybe one of the remaining "valid" comparisons could use aligned stars at the start of each line for variation ?
• What about combining the "Block comment text should start on a new line." and the "The first line should not be empty." standards as they kind of enforce the same thing ?
• I seem to be missing some guidance on the indentation requirements for the star of the docblock closer (LastLineIndent error code) ?

I also wonder what guided the order of the <standard> blocks. To me, it feels a bit all over the place, jumping from start of block comment formatting to end formatting, to within formatting, to before formatting etc...
I can imagine the documentation may be easier to take in if the rules were ordered to follow the structure of the docblock ?

Lastly, the <em> tags should be used in both the "valid" as well as the "invalid" code samples. They seem to be missing from the "valid" ones now.

Let me know if you have any questions, if not, I look forward to the next iteration.

[jrfnl]

I haven't checked, but should it just be on a new line or should it be on a line by itself ? (i.e. with nothing after it either)

[costdev]

For example:

<?php
/*
 * A block comment
 * with multiple lines.
 *
 * And a second paragraph.
 */doSomething();

This triggers Squiz.Commenting.BlockComment.NoEmptyLineAfter.

Do you think an example of this should be included in a code comparison here, or should I add a second example (in the same code comparison block) here?

[costdev]

What about including a short description of what is considered a "block comment" in the first <standard> block ?

Sure!

First <standard> has five code comparisons - could the same information be conveyed in maybe two code comparisons ?
And maybe one of the remaining "valid" comparisons could use aligned stars at the start of each line for variation ?

That sounds good. I can merge the /** */, /** **/, /* **/ into the first "invalid" comparison and //, # into the second, and use aligned stars in the second "valid" comparison.

What about combining the "Block comment text should start on a new line." and the "The first line should not be empty." standards as they kind of enforce the same thing ?

While they enforce separate things, for documentation it's probably not necessary to be as verbose as I was in separating these two. I think "Block comment text should start on a new line." probably covers it well, so I can even just remove "The first line should not be empty.".

I seem to be missing some guidance on the indentation requirements for the star of the docblock closer (LastLineIndent error code) ?

I wasn't totally sure about covering this one separately, as it felt covered by the "If there are no asterisks" and "If asterisks are used" entries. Would you like me to cover this one separately anyway?

I also wonder what guided the order of the <standard> blocks. To me, it feels a bit all over the place, jumping from start of block comment formatting to end formatting, to within formatting, to before formatting etc... I can imagine the documentation may be easier to take in if the rules were ordered to follow the structure of the docblock ?

Originally, I was following the order of the errors in the sniff. Afterwards, I felt they were a bit all over the place, so I tried another order which focused on establishing correct openers and closers, then addressed the contents of the comment. Since that too feels a bit all over the place, I'm happy to try a different order.

How does this sound?

A block comment immediately after an open tag should not have a preceeding blank line.
A block comment should use /* */.
A block comment should not be empty.
Single line block comments are not allowed.
Block comment text should start on a new line.
A block comment should start with a capital letter.
If there are no asterisks at the start of each line, the contents of the docblock should be indented by at least 4 spaces.
If asterisks are used, they should be aligned.
The block comment closer should be on a new line.
There should be an empty line after the block comment.

Lastly, the <em> tags should be used in both the "valid" as well as the "invalid" code samples. They seem to be missing from the "valid" ones now.

Woops. I got it into my head that only the "invalid" needed to be highlighted. No idea how that happened since it's explicitly stated in the contributing guidelines. 😅

[costdev]

Follow-up on the explanation of a block comment:

I want to make sure I capture the right concept in the explanation.

• They're definitely used to provide a longer explanation of code.
• They're also sometimes used to draw more attention to a piece of code than a single-line comment would, even if the block comment only has one line of text inside it. I'm not sure if this is strictly relevant here though.
• While /* */ are commonly used to comment out blocks of code, that's not really relevant here. It's commented out code, not a block comment.

If you agree with the above, what do you think of this for the first <standard> block?

A block comment contains multiple lines and provides a longer explanation of code, or draws more attention to it than a single-line comment would.
    
Block comments should use /* */. <-- This would of course be replaced by whatever becomes our new first <standard> block.

[jrfnl]

@costdev Thank you for making all those changes. When looking at it now, it reads very naturally, so job well done!

I only have one nitpick left and then this is ready for merge.

[jrfnl]

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 ?

Suggested change

	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.
	A block comment is a multiline comment delimited by an opener "/*" and a closer "*/" which are each on their own line with the comment text in between.

[costdev]

From what I can see, UK English uses multi-line, US English doesn't.

Which would you prefer?

[jrfnl]

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).

[costdev]

Checking a small number of differences, such as multi-line vs multiline, ise vs ize, colour vs color, 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. Obviously color/background-color in CSS doesn't count, but for example, there's NamedColourSniff and T_COLOUR, but also the private colorizeVariableInput() method in the Help utility class.

Regarding this PR, it looks like multi-line is used more often outside of things like PHP class names where the hyphen isn't an option. I'll update the PR to use multi-line consistently. At least it'll make it easier to change in one go should the variant of English be changed in the future.

[jrfnl]

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 ?

[jrfnl]