File::getDeclarationName(): stop accepting tokens for non-named structures

[jrfnl]

Description

Tests: rename some test case files

... in anticipation of additional test case files for parse error being added.

Various sniffs: add extra tests with live coding/parse errors

Includes fixing up some inline comments for sniffs which don't search for closures, but could encounter live coding.

Includes one minor bug fix/defensive coding fix in the Squiz.Commenting.ClosingDeclarationComment sniff.

File::getDeclarationName(): stop accepting tokens for non-named structures

The File::getDeclarationName() method - for historic reasons - accepted the T_CLOSURE and T_ANON_CLASS tokens, even though these structures will never have a name, and returned null for those tokens.

This commit changes the File::getDeclarationName() method to no longer accept those tokens and throw an exception if they are passed to the method instead.

As a secondary change, when the name of a valid structure cannot be determined, the method will now no longer return null, but will return an empty string.
This normalizes the return type of the method to always return a string (or throw an exception).

Includes updated unit tests to match.

Related to squizlabs/PHP_CodeSniffer#3766

---

All PHPCS native sniffs using the File::getDeclarationName() method have been reviewed and where necessary fixed to allow for this change.

Also note that in some cases, the sniff already contained sufficient protection and in other cases, the fact that the method will no longer return null, meant that the sniff code could be simplified.

List of sniffs reviewed:

• AbstractScopeSniff
• Generic.Classes.DuplicateClassName
• Generic.CodeAnalysis.UnusedFunctionParameter
• Generic.CodeAnalysis.UselessOverridingMethod
• Generic.NamingConventions.AbstractClassNamePrefix
• Generic.NamingConventions.CamelCapsFunctionName
• Generic.NamingConventions.ConstructorName
• Generic.NamingConventions.InterfaceNameSuffix
• Generic.NamingConventions.TraitNameSuffix
• PEAR.Commenting.ClassComment
• PEAR.Commenting.FunctionComment
• PEAR.Functions.FunctionDeclaration
• PEAR.NamingConventions.ValidFunctionName
• PSR1.Methods.CamelCapsMethodName
• PSR2.Methods.MethodDeclaration
• Squiz.Classes.ClassFileName
• Squiz.Classes.SelfMemberReference
• Squiz.Commenting.ClassComment
• Squiz.Commenting.ClosingDeclarationComment
• Squiz.Commenting.FunctionComment
• Squiz.Functions.GlobalFunction
• Squiz.NamingConventions.ValidFunctionName
• Squiz.Scope.MethodScope

👉 The changes to the PEAR/FunctionDeclaration sniff will be easier to review while ignoring whitespace.

Suggested changelog entry

Changed:

• The File::getDeclarationName() method will no longer accept T_ANON_CLASS or T_CLOSURE tokens.
  • A RuntimeException will be thrown if these tokens are passed.
• The File::getDeclarationName() method will now always return a string (or throw an Exception).
  • Previously, the method would return null if the name could not be determined, like during live coding.
    Now it will return an empty string in those situations.