See also
📌
Use C::class instead of 'C' for strings holding class names, to facilitate "find usages" in IDEs.
Needs work
.
Problem
Sometimes function names are specified as strings.
In some cases, the IDE (*) can actually figure out that these are function names. E.g. in the snippet below, the IDE understand that function_exists() has a parameter which is a function name.
if (function_exists('foo')) {
[..]
In other cases, there is really no way for an IDE to know that a string is a function name.
function hook_menu() {
$items['example'] = array(
'title' => 'Example Page',
'page callback' => 'example_page',
'access arguments' => array('access content'),
'type' => MENU_SUGGESTED_ITEM,
);
return $items;
}
(this is Drupal 7, but we might still have code like this in Drupal 8).
(*) When I say IDE I usually talk about the IDE that I use myself, which is PhpStorm. In general, we should assume that IDEs evolve over time, but that there are limitations for how far they can go.
Proposed solution
Put a @see comment in the line above the string, like so:
function hook_menu() {
$items['example'] = array(
'title' => 'Example Page',
/* @see example_page() */
'page callback' => 'example_page',
'access arguments' => array('access content'),
'type' => MENU_SUGGESTED_ITEM,
);
return $items;
}
With this added @see comment, the IDE can now
- "find usages" for function example_page().
- navigate to the function if you click the @see comment.
I am using the /* */ comment syntax instead of inline // comment syntax, because my IDE ignores the @see if it is in //. I had a discussion about this somewhere in the PhpStorm issue queue.
The exact syntax might require some bikeshedding. And maybe some part of the discussion should happen elsewhere.