Generic/FunctionCallArgumentSpacing: improve XML documentation

[rodrigoprimo]

Description

Generic/FunctionCallArgumentSpacing: update XML doc to remove info about spacing around equal sign

The FunctionCallArgumentSpacing sniff used to check for spacing around the equal sign in the arguments of a function declaration. But this was removed in squizlabs/PHP_CodeSniffer#2399
(commit feeda47).

This commit updates the sniff XML doc to reflect this change.

Generic/FunctionCallArgumentSpacing: fix code examples in the XML doc

The code examples in the XML documentation of this sniff were incorrect, as the sniff does not check spacing in function argument definitions. It only checks spacing in function and method calls.

As far as I could check, this has always been the case, or at least it has been the case for a long time. Since tests were added for this sniff when it was part of the PEAR standard and called MethodCallArgumentSpacing, it ignored function definitions and checked only function calls:

squizlabs/PHP_CodeSniffer@7b84951#diff-56e2f69852c3071fbf86d20fbb49f38dae17cff8731154d8b1b7495c4ad8eeb0R24-R27

Here is the sniff code where it ignores function definitions:

PHP_CodeSniffer/src/Standards/Generic/Sniffs/Functions/FunctionCallArgumentSpacingSniff.php

Lines 55 to 66 in 57a9ed7

	// Skip tokens that are the names of functions or classes
	// within their definitions. For example:
	// function myFunction...
	// "myFunction" is T_STRING but we should skip because it is not a
	// function or method *call*.
	$functionName = $stackPtr;
	$ignoreTokens = Tokens::$emptyTokens;
	$ignoreTokens[] = T_BITWISE_AND;
	$functionKeyword = $phpcsFile->findPrevious($ignoreTokens, ($stackPtr - 1), null, true);
	if ($tokens[$functionKeyword]['code'] === T_FUNCTION || $tokens[$functionKeyword]['code'] === T_CLASS) {
	return;
	}

Generic/FunctionCallArgumentSpacing: improve XML documentation

• <documentation> title now matches the sniff name
• Mention in the description that the sniff is about function and method calls.
• <standard> and <code> descriptions now mention that the sniff also checks for spaces before the comma.

Suggested changelog entry

Generic.Functions.FunctionCallArgumentSpacing: minor fixes and improvements to the XML documentation

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]

Nice finds! Looking good. I just have one small suggestion for the description to improve the accuracy and readability.

[rodrigoprimo]

Thanks for your review, @jrfnl. I just committed the change you suggested, and this PR is ready for another review.

[jrfnl]

Thanks @rodrigoprimo !

I will rebase the PR to squash the fix-up commit into the correct atomic commit. Merging once the build has passed.