Proper PHPDoc for switch statement with object return value

Question

If you could be so kind to take a look at the project I'm working on at this line ( the function api() ).

https://github.com/wtfzdotnet/php-tmdb-api/blob/develop/lib/Tmdb/Client.php#L79

What is the correct way here for IDE's to actually auto complete the methods of the returned object instances? The way I'm using it right now returns all the methods from all the possible return objects.

Short; how do I make sure the IDE recognizes auto-complete methods for objects being returned are defined by a switch statement? I'd like to know what the proper way is for the IDE auto-completing this, and as well the best PHPDoc strategy ( It does have an interface, which however is empty for time being ).

Update 1

As the first comment suggested I tried to adjust the case for 'movies' as a test to:

case 'movies':
    return $this->getMovieApi();

and added

/**
 * @return Api\Movies
 */
private function getMovieApi(){
    return new Api\Movies($this);
}

But this does not function as expected when trying to call:

$client->api('movies')->[try_autocomplete]

However when I change the scope of getMovieApi to public and call this directly as:

$client->getMovieApi()->[try_autocomplete]

It works as expected, however I really prefer my initial method, as this looks cleaner ( atleast to me ). Is it really impossible to get proper auto-completion if return values are derived from a switch statement?

Answer 1

Proper way would be create all this get methods with they own @return: getConfiguration, getAuthentication and etc.