Right now phpdocs comments within code are 100% forbidden, and the code-checker always report them that way with message:

Inline doc block comments are not allowed; use "/* Comment */" or "// Comment" instead

But they are useful, especially for IDEs, helping them to find the type (class) of a given variable and its methods, attributes.

So this is about to consider when we could whitelist declarations of this type:

/** @var type $name */

$name = something_that_retuns_a_type();

A.k.a, a inline phpdoc comment describing a variable immediately followed by an assignment to that variable.

One example (out from lots), that caused this to be created:

https://tracker.moodle.org/browse/MDL-46051?focusedCommentId=304616&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-304616

To be discussed before implementation, ciao