While upgrading Phan for AbuseFilter, I noticed a decent amount of warnings coming from OOUI, see P8143. Looking at OOUI codebase, it's pretty obvious why this happens: many (if not all) widgets, layouts etc. have something like this in the constructor:
/**
* @param array $config Configuration options
* @param string $config['align'] ...
* @param array $config['errors'] ...
* @param array $config['notices'] ...
* @param string|HtmlSnippet $config['help'] ...
*/
public function __construct( array $config = [] ) {Which is to say, every element of the $config array is documented as a stand-alone parameter. This is very confusing for Phan, and I'm unsure whether it's a valid docblock annotation. It also has to be fixed somehow, because otherwise any piece of code using OOUI will have to add tons of suppressions.
However, before starting to mass-edit all docblocks, I'd like to know what the proposed solution is. An idea is to replace @param with some padding, so to have:
(Prop 1)
/** * @param array $config Configuration options * string $config['align'] ... * array $config['errors'] ...
or similar format.
Prop 1b
/** * @param array $config Configuration options * $config['align'] string Blah blah * $config['errors'] array Blah blah
Prop 2
/**
* @param array $config Configuration options
* $config = [
* 'align' => string Blah blah
* 'errors' => array Foo bar bazProp 2b
/**
* $config = [
* here goes description in one of the above styles
* ]
*
* @param array $config Configuration options
