Quoting http://drupal.org/node/1354#functions
After the long description, each parameter should be listed with a @param directive, with a description indented by two extra spaces on the following line or lines.
Since Drupal 8 will be heavily object oriented, and starts to use type hint for classes in parameters, it may worth the shot to discuss about this. Most comments in core when we pass entities as parameters always end up like this:
/**
* @param $comment
* A comment object.
*/
function do_something($comment) {}
Now, with type hinting, it becomes:
/**
* @param Comment $comment
* A Comment object.
*/
function do_something(Comment $comment) {}
I wanted to notice that the "A Comment object." line is redundant with both the @param directive, and the function or method signature. I think we could revisit the coding standard I quoted upper in order to avoid those redundancy.
If the documentation has nothing more to say that the paramater is an instance of the Comment class, I don't see the need to tell it. We probably should allow the developer not to comment this @param directive if it has nothing more to bring than the function signature already does.
Closed: duplicate
Documentation
It involves compliance with, or the content of coding standards. Requires broad community agreement.
Not all content is available!
It's likely this issue predates Contrib.social: some issue and comment data are missing.
I read the issue summary and comments. The consensus seems to me to not make a change. @jhodgdon said this well in
So at the risk of a small amount of redundancy, my suggestion would be that we keep the standards as they are, and encourage people to add some value to the documentation.
There is another issue that proposes a very specific change for the @param docs, I am closing this as a duplicate. 📌 Allow omitting doxygen when type and variable name is enough Active