Add documentation for WordPress.PHP.RestrictedPHPFunctions

[gogdzl]

Related to #1722

[GaryJones]

Suggested change

	add_action( 'init', function() {
	return foo( 'bar' );
	} );
	add_action( 'init', <em>function() {
	return foo( 'bar' );
	}</em> );

We can highlight the good bit of this snippet to focus on.

[rodrigoprimo]

Thanks for another PR adding user documentation for a sniff, @gogdzl! I left some comments with suggestions for us to discuss.

[rodrigoprimo]

Suggested change

	The restricted function create_function() should not be used.
	The function create_function() should not be used.

[rodrigoprimo]

I wonder if it is a good idea to include an example with a declared named function as well (and then also update the title attribute)? Maybe it is just me, but it took me a second to properly read the sentence Please use declared named or anonymous functions instead. and to realize that functions applies to both declared named and anonymous. My first thought was "what is a declared named"?

[jrfnl]

Looks like this phrase is also used in the error message thrown by the sniff.

While the phrase is no longer used in the docs per #2693, we may still want to consider updating the phrasing in the actual sniff.

@rodrigoprimo Want to add that to your list ?

[jrfnl]

Never mind. Figured I might as well fix it straight away: #2702

[rodrigoprimo]

I'm not against mentioning here that anonymous functions are also known as closure. But if it is important to provide this information, I believe it should also be present in the description of the <standard> block.

[rodrigoprimo]

I'm unsure if including a call to add_action() here helps understand what the sniff does or if it just adds noise. Usually, the examples are minimalistic, and just calling calling create_function() or calling it and assigning the returned value to a variable is enough?

[rodrigoprimo]

@gogdzl, I was just wondering if you'll have a chance to finish this off in the near future. It would be great if this PR could be included in the next WPCS release.

If you haven't got time or lost interest, please let us know and we'll see if we can find someone to take over. Thanks!

[rodrigoprimo]

@gogdzl, please let us know within a week if you are still interested in finishing this PR. If we don't hear back from you, we will presume you don't have time, and we will see if we can find someone else to take over and finish it. Thanks for your work so far!