phpdoc @return with lazy loading

Question

I don't know how to documents my methods for autocompletion.

My model Training has a getAnimators() method who returns a Db_MysqlResult which implements SeekableIterator and Countable. This Db_MysqlResult will create my Animator objects when I iterates on it, for example :

<?php
foreach ($training->getAnimators() as $animator) {
    // Autocompletion shows me next, seek, etc. not getName
    echo $animator->getName(); 
}
?>

I can write @return Animators[] in my getAnimators() even if it is not true because it returns a Db_MysqlResult?

Thanks in advance for your help.

Answer 1

If you are looking for your $animator variable to autocomplete its methods, your best bet may be to add an @var line hint in there:

/** @var Animator $animator */
echo $animator->

Some IDEs have the ability to recognize that @var line as a type hint and use it to give you autocompletion.

However, I'm not aware of any IDE that will recognize your return value of $training->getAnimators() and automatically know the type for $animator just from them being tied together in that foreach().