[Documentation] PSR12 - Control Structure Spacing

[dingo-d]

The PR contains the documentation for the PSR12/ControlStructures/ControlStructureSpacing sniff.

Description

This PR will add the documentation for the above-mentioned sniff, according to the official standard definitions.

Note that some rules mentioned in the above definitions are covered by other rulesets. So they were not added to the documentation, as they are not a part of the Control Structure Spacing sniff.

Suggested changelog entry

Add documentation for the PSR12 ControlStructureSpacing sniff

Related issues/external references

Part of #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]

Thanks @dingo-d for taking this on!

Could you have a look at the inline comments please ?

Also - would it be an idea to have a separate standard block for single line control structure conditions vs multi-line control structure conditions ?
And maybe a separate standard block about the "each expression on its own line and indented once" rule ?

[dingo-d]

Also - would it be an idea to have a separate standard block for single line control structure conditions vs multi-line control structure conditions ? And maybe a separate standard block about the "each expression on its own line and indented once" rule ?

Yeah, I was wondering what would be the best way to split this documentation, as there are quite a bit of it. Will see how to best split it with separate standard blocks 👍🏼

[dingo-d]

@jrfnl Can you take another look? I've added the additional standards, so it should be more readable now.

[jrfnl]

@dingo-d Please have another look.

May I also ask you to have a critical look at your other open PRs based on the review comments you've received in this PR and others before this ?

[jrfnl]

Should the "no space after the keyword" rule get its own code sample ? Or could this be included in this invalid code sample ?

Suggested change

	if <em>( </em>$expr) {
	if<em> ( </em>$expr) {

[dingo-d]

Technically, this sniff doesn't check for the space after the keyword. This is covered by the Squiz.ControlStructures.ControlSignature.SpaceAfterKeyword sniff, so I'm not sure if we should include it in the documentation for this sniff.

I'm all for removing squiz rules from the PSR12 ruleset, and just modifying the ControlStructuresSpacing sniff to include all the checks as in the PSR-12 documentation for control structures, but I think that would be something for PHPCS v4.

[jrfnl]

You are 100% correct! I thought this sniff was checking that too, but you are right, it does not. The updated standards description from commit a1795c1 confused me as that _does_mention the space after the control structure keyword.

In other words: No, there should not be a code sample for space after keyword, but the first <standard> block will need to be updated to remove the mention of the spacing after the keyword.

[jrfnl]

And this bit ", and one space between the closing parenthesis and the opening brace" will also need to be removed as that is also not checked via this sniff.

[dingo-d]

Yes, you're right about these. Will fix them now 👍🏼

[dingo-d]

I think I now have this docs fixed @jrfnl. See my remark about the space after the keyword above.

I'm also not 100% sure about the <em> tag placement tho.

[jrfnl]

Thanks @dingo-d for working on this! Ready for merge 🎉