The following @see references to functions with parameter indicators are both accepted fine by the API module:
/**
* ..
*
* @see system_settings_form(array $form)
*
* @see ooe_form_admin(array $form, array &$form_state)
* ..
*/
The API module generates for the above a nice link to each recognised function following be the parameter indicators as plain text:
- system_settings_form(array $form)
- ooe_form_admin(array $form, array &$form_state)
But Coder generates for these the following error report:
ERROR | The @see reference should not contain any additional text
The following (just showing the array parameter type, leave out the parameter variable) for some reason does not trip Coder:
* @see system_settings_form(array)
The following are also accepted by Coder:
* @see system_settings_form()
*
* @see ooe_form_admin()
*
But these do not include the sometimes very useful parameter indicators in the API output, they just give:
- ooe_form_admin()
I would like support for such indicators of function parameters as shown at the top.
The Drupal doc standards for @see currently states:
Drupal standards: Each @see reference is on its own line, with no additional text beyond the item being referenced.
I see no reason why 'the item being referenced' can't be a complete method or function signature, and it could be identified as a function name followed by something in () parentheses.
Comments
Comment #1
klausiwhy would you name the parameters of a function in an @see reference? The reference should only point to the function where you can read up all about its parameters?
Could you point me to a Drupal core @see reference where we are doing this?
The error is triggered because Coder sniffer consider everything after a space as additional text, which should not be used in @see references.
Comment #2
webel commented@klausi Thanks for reply and questions:
Purely for educational purposes, so that one can conveniently see the parameters of the referenced function in the API docs. In practice it works fine with the API module.
It's purely a matter of convenience; I don't want myself or other readers to have to leave an API module generated web page to have to find the parameter signature.
Probably not, there probably aren't any, but I can point you to some API pages from my own educational module that shows it working and why I like it.
This one references and external Drupal function drupal_render(&elements):
- public function IRender::setPrefix
This one references (from a delegate Class method to the matching .module file function) an internal function ooe_form_demo_submit($form, &$form_state):
- public function OoeBridge::form_demo_submit
Please note how the API module happily includes say a link on the referenced function, followed by the hand-entered function signature text, like this:
See also:
ooe_form_demo_submit($form, &$form_state)
So another solution (way to meet my requirement) is to have the API module pull the function signature.
Yes, that's clear to me. So having the API module pull the entire signature and link it might be a better approach.
Comment #3
klausiI'm closing this because I think the @see references are not meant to duplicate function signatures, so the error is fine as is.