Improve Title Resolver return documentation

Interface docs:

   * @return array|string|null
   *   The title for the route.
   */
  public function getTitle(Request $request, Route $route);

string as a typehint tends to imply that as long as a Stringable object is returned, it's fine. But https://www.php.net/manual/en/class.stringable.php only exists since PHP 8, which is why the interface docs indicate just string.

In Drupal 10, we'll be able to make this better though!

What do you think about this as an alternative? 😊

Why is this a support request?

Makes sense to me. And my ide will thank you!

Will there be any problems if we add native PHP typehints to the method?

@Chi If we don't have to care about PHP 7 support, then we indeed could … if we did a BC break: https://3v4l.org/WYop7

Code in that experiment:

<?php

class Request {}
class Route {}
// Before: docs only: array|string|\Stringable|null
/*
interface FooInterface {
    public function getTitle(Request $request, Route $route);
}
*/
// If we use native typehints instead
interface FooInterface {
    public function getTitle(Request $request, Route $route): null|array|string|\Stringable;
}

// This is an implementation written against the original, i.e. with no return types specified. We should not break it.
class SomeFoo implements FooInterface {
    public function getTitle(Request $request, Route $route) {
        return 'yay';
    }
}

$test = new SomeFoo();
var_dump($test->getTitle(new Request(), new Route()));

… so AFAICT, we unfortunately can't do that.

@Wim Leers, aren't BC breaks still acceptable for Drupal 10?

Drupal 10 is in beta, so … no. The API is frozen.

Moving back to RTBC seemed ot be a random failure.

Fixing the issue title to match what we're doing

Committed and pushed 6d34fc2b74 to 10.1.x and efeb6f0ec2 to 10.0.x. Thanks!