[Documentation] Squiz: Function Spacing

[jaymcp]

Description

This PR adds documentation for the Squiz.WhiteSpace.FunctionSpacing Sniff.

Suggested changelog entry

Add documentation for the Squiz Function Spacing Sniff

Related issues/external references

Part of https://github.com/PHPCSStandards/PHP_CodeSniffer/issues/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.
• [x] Documentation improvement

PR checklist

• [x] I have checked there is no other PR open for the same change.
• [x] I have read the Contribution Guidelines.
• [x] 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.
• [x] I have verified that the code complies with the projects coding standards.
• [ ] [Required for new sniffs] I have added XML documentation for the sniff.

[jaymcp]

@jrfnl apologies for the delay since my last PR. FYI my GitHub handle has now changed (jonmcp => jaymcp).

[jaymcp]

Thanks @jrfnl!

In the docs, it mentions "within a statement group or control structure" in a couple of places. Where does this come from ? And is this clear enough ?

I struggled with the wording of this; I couldn't think of a reasonably concise way of explaining the expectations of this rule in a way that also provided enough context. I landed on "statement group", but I agree that it's not clear enough. I'd appreciate your advice here.

While the sniff allows for configuring different expectations for the spacing before/after the first/between/last function, in its default state, the expectations are the same: 2 blank lines. Have you considered combining the standards/code samples ? And if so, what made you decide against that ?

I decided on that purely because they have different error codes. Would you like me to combine them?

[jrfnl]

In the docs, it mentions "within a statement group or control structure" in a couple of places. Where does this come from ? And is this clear enough ?

I struggled with the wording of this; I couldn't think of a reasonably concise way of explaining the expectations of this rule in a way that also provided enough context. I landed on "statement group", but I agree that it's not clear enough. I'd appreciate your advice here.

Well, let's break it down: what are you trying to say with it ? (in your own words, doesn't have to ready for the docs, just trying to get a feel for why the phrase was added)

While the sniff allows for configuring different expectations for the spacing before/after the first/between/last function, in its default state, the expectations are the same: 2 blank lines. Have you considered combining the standards/code samples ? And if so, what made you decide against that ?

I decided on that purely because they have different error codes. Would you like me to combine them?

Not necessarily, though I wonder if the amount of examples is overkill. Can you think of a way to still keep the gist of the code samples intact with a more minimal set of examples ? (and "no", is, of course, also a potential answer)

[jrfnl]

@jaymcp Just checking in: had a chance to think my question over yet ?

[jaymcp]

Apologies for the further delay, @jrfnl, and thanks for your continued patience.

In the docs, it mentions "within a statement group or control structure" in a couple of places. Where does this come from ? And is this clear enough ?

I struggled with the wording of this; I couldn't think of a reasonably concise way of explaining the expectations of this rule in a way that also provided enough context. I landed on "statement group", but I agree that it's not clear enough. I'd appreciate your advice here.

Well, let's break it down: what are you trying to say with it ? (in your own words, doesn't have to ready for the docs, just trying to get a feel for why the phrase was added)

I was trying to articulate that, not only will this sniff check functions in the top-level of a file and in perhaps more obvious places like object structures, but also in control structures and whatnot. I could perhaps have said something like "There should be exactly 2 blank lines before/after a function declaration.", but wasn't 100% confident that that was accurate either.

While the sniff allows for configuring different expectations for the spacing before/after the first/between/last function, in its default state, the expectations are the same: 2 blank lines. Have you considered combining the standards/code samples ? And if so, what made you decide against that ?

I decided on that purely because they have different error codes. Would you like me to combine them?

Not necessarily, though I wonder if the amount of examples is overkill. Can you think of a way to still keep the gist of the code samples intact with a more minimal set of examples ? (and "no", is, of course, also a potential answer)

We could probably remove the first and last code samples without impacting readability at all, in my opinion. I wanted to illustrate that this sniff did not only apply to object structures, but we don't need examples of all of them, and perhaps not more than one example for a conditional. I now realise, though, that I've not included an example similar to that shown in one of the unit tests.