Right now we are only allowing PHPDocs @ some well defined places. See http://docs.moodle.org/dev/Coding_style#Files and next sections (basically files, classes, interfaces, methods, and properties).

But that's not enough to facilitate IDEs autocompletion for local variables, mainly because the @return specification does not allow hinting the type of arrays.

For example, this code:

$files = $this->get_draft_files('rolepreset');

retuns an array of stored_file objects, but the IDE has no way to know it, so it won't bring you autocompletion for any use of those variables. So, for example:

$file = reset($files);

$file->.... won't autocomplete at all.

Given that, there are some developers that have started using this as a technique to bring autocompletion working:

/** @var stored_file $file */

$file = reset($files);

$file->.... will autocomplete ok.

But, right now, that's against the coding style because we don't allow PHPDocs for local variables at all (and the code checker reports it).

In the other side, looking for more information, I ended here where it points about some IDEs (Netbeans, phpStorm..) being able to provide autocompletion by using this syntax in return types in the called function / method:

/**

 * ....

 * ....

 * @return stored_file[]

 */

function get_draft_files() {...}

By using that we are:

1) Allowing IDEs to autocomplete better. Sure it does not cover everything (nested array/object structures...) but at least the very common case of simple arrays.
2) Makes not needed to support inline PHPDocs for local variables.
3) Provides better PHPDoc documentation, being able to specify the class of the array (assuming system X will be able to process that).

======

Offtopic, note that also it's possible to get the IDEs autocompleting sometime by casting so:

$file = (stored_file)reset($files);

will lead to better autocompletion, but we should not be casting everywhere, just for hinting IMO, so I've left that out as a possible solution.

=====

So, this is, basically about to decide:

A) Should we allow PHPDocs for local variables hinting (yes/no).
B) Should we move from "@return array" to more specific "return type[]" syntax (yes/no). Note this requires research to verify how IDEs and X-like systems support it.

Let's discuss about this. Ciao