The '_title_callback' from the route defaults should be used for dynamic page titles

In #2032535: Resolve 'title' using the route and render array A static _title was added to the route defaults. With #2076085: Resolve the need for a 'title callback' using the route this change is extended so dynamic titles can be handled with a callback. This should be used in preference to setting #title on the page render array, since this callback is accessible while building breadcrumbs and similar contexts where the full page is not rendered.

Titles on routes now can be set on various ways, depending on your usecase.
Previously just drupal_set_title() was called in whatever place. The following usecases exists:

1. Static title:
   For static titles you set a '_title' on the routing definition:

   block.admin_add:
     path: '/admin/structure/block/add/{plugin_id}/{theme}'
     defaults:
       _controller: '\Drupal\block\Controller\BlockAddController::blockAddConfigureForm'
       _title: 'Configure block'
     requirements:
       _permission: 'administer blocks'
   

2. Dynamic title:
   If you write a controller and you need a dynamic title, for example depending on the site configuration, use _title_callback in the route defaults.

   mymodule.test:
     path: '/mymodule/test'
     defaults:
       _controller: '\Drupal\mymodule\Controller\Test::getContent'
       _title_callback: '\Drupal\mymodule\Controller\Test::getTitle'
   

   class Test {
   
     /**
      * Returns a page title.
      */
     public function getTitle() {
       return  'Foo: ' . \Drupal::config()->get('system.site')->get('name');
     }
   
     /**
      * Returns a page render array.
      */
     public function getContent() {
       $build = array();
       $build['#markup'] = 'Hello Drupal';
       return $build;
     }
   }
   

The #title from the page array will still be used as a final override.

Also updated https://drupal.org/node/2067859 to be comprehensive.