Return the correct typehint when Drupal::classResolver() is called with a class string

Problem/Motivation

As per #3490713: Return the correct typehint when Drupal::service() is called with a class string, but for \Drupal::classResolver().

Calling \Drupal::classResolver($class) does not return a type hint for PHPStan validation and IDE completion.

We can provide PHPStan annotations to infer the return type when the class string passed in as an argument.

Steps to reproduce

Proposed resolution

We can use Generics and conditional return types to acheive this.

For example:

<?php
  /**
   * ...
   *
   * @param class-string<T> $class
   *   (optional) A class name to instantiate.
   *
   * @template T of object
   *
   * @return ($class is class-string<T> ? T : \Drupal\Core\DependencyInjection\ClassResolverInterface)
   *   The class resolver or if $class is provided, a class instance with a
   *   given class definition.
   *
   * ...
   */
public static function classResolver($class = NULL) {
?>

Since \Drupal::classResolver() is effectively a wrapper around ClassResolverInterface::getInstanceFromDefinition() we should update the annotation there too. Note it is slightly different as that does not allow NULL, and explicitly allows a service id.

Remaining tasks

User interface changes

Introduced terminology

API changes

Data model changes

Release notes snippet