Url::getInternalPath() is marked deprecated but won't be removed for 8.0.x, so update the docs

I am trying to figure out why this is really deprecated, apart from the purist view that it should not be used as described in the comment. I found only one change record where this method is mentioned.

On the other hand, there are lots of references in core where this method is used and there doesn't seem to be a suitable substitute. We need to have a strong concise substitute before we remove a helper method.

includes/common.inc:230:    $path = \Drupal::routeMatch()->getRouteName() ? Url::fromRouteMatch(\Drupal::routeMatch())->getInternalPath() : '';
includes/theme.inc:701:            $system_path = $url->getInternalPath();
lib/Drupal/Core/Entity/Entity.php:211:      return $uri->getInternalPath();
lib/Drupal/Core/Path/PathMatcher.php:104:        $this->isCurrentFrontPage = ($url->getRouteName() && $url->getInternalPath() === $this->getFrontPagePath());
lib/Drupal/Core/Routing/NullGenerator.php:59:  protected function getInternalPathFromRoute(Route $route, $parameters = array()) {
lib/Drupal/Core/Routing/UrlGenerator.php:94:    $path = $this->getInternalPathFromRoute($route, $parameters);
lib/Drupal/Core/Routing/UrlGenerator.php:114:  protected function getInternalPathFromRoute(SymfonyRoute $route, $parameters = array()) {
lib/Drupal/Core/Routing/UrlGenerator.php:159:    $path = $this->getInternalPathFromRoute($route, $parameters);
lib/Drupal/Core/Url.php:91:   * Stores the internal path, if already requested by getInternalPath
lib/Drupal/Core/Url.php:531:  public function getInternalPath() {
lib/Drupal/Core/Utility/LinkGenerator.php:114:        $system_path = $url->getInternalPath();
modules/aggregator/src/Tests/AggregatorRenderingTest.php:65:    $this->drupalGet($feed->urlInfo()->getInternalPath());
modules/config_translation/src/ConfigNamesMapper.php:216:    return Url::fromRoute($this->getBaseRouteName(), $this->getBaseRouteParameters())->getInternalPath();
modules/config_translation/src/ConfigNamesMapper.php:253:    return Url::fromRoute($this->getOverviewRouteName(), $this->getOverviewRouteParameters())->getInternalPath();
modules/content_translation/src/Form/ContentTranslationDeleteForm.php:83:      $path = $this->entity->urlInfo()->getInternalPath();
modules/menu_link_content/src/Form/MenuLinkContentForm.php:234:      // @todo Url::getInternalPath() calls UrlGenerator::getPathFromRoute()
modules/menu_link_content/src/Form/MenuLinkContentForm.php:237:      $default_value = $url->getInternalPath();
modules/path/src/Plugin/Field/FieldType/PathItem.php:62:      if ($path = \Drupal::service('path.alias_storage')->save($entity->urlInfo()->getInternalPath(), $this->alias, $this->getLangcode())) {
modules/path/src/Plugin/Field/FieldType/PathItem.php:79:      \Drupal::service('path.alias_storage')->save($entity->urlInfo()->getInternalPath(), $this->alias, $this->getLangcode(), $this->pid);
modules/path/src/Plugin/Field/FieldType/PathItem.php:89:    \Drupal::service('path.alias_storage')->delete(array('source' => $entity->urlInfo()->getInternalPath()));
modules/path/src/Plugin/Field/FieldWidget/PathWidget.php:36:      $conditions = array('source' => $entity->urlInfo()->getInternalPath());
modules/path/src/Plugin/Field/FieldWidget/PathWidget.php:47:      'source' => !$entity->isNew() ? $entity->urlInfo()->getInternalPath() : NULL,
modules/shortcut/shortcut.module:300:    $link = Url::fromRouteMatch(\Drupal::routeMatch())->getInternalPath();
modules/shortcut/src/Tests/ShortcutLinksTest.php:142:    $this->drupalPostForm('admin/config/user-interface/shortcut/link/' . $shortcut->id(), array('title[0][value]' => $new_link_name, 'link[0][uri]' => ltrim($shortcut->getUrl()->getInternalPath(), '/')), t('Save'));
modules/system/src/Tests/Menu/BreadcrumbTest.php:269:      $link_path = $link->getUrlObject()->getInternalPath();
modules/system/system.module:242:    $path_args = explode('/', Url::fromRoute('<current>')->getInternalPath());
modules/system/system.module:255:    $path_args = explode('/', Url::fromRoute('<current>')->getInternalPath());
modules/system/system.module:610:        'path' => \Drupal::routeMatch()->getRouteName() ? Url::fromRouteMatch(\Drupal::routeMatch())->getInternalPath() : '',
modules/system/system.module:635:  $current_path = \Drupal::routeMatch()->getRouteName() ? Url::fromRouteMatch(\Drupal::routeMatch())->getInternalPath() : '';
tests/Drupal/Tests/Core/UnroutedUrlTest.php:194:    $this->assertNull($urls[0]->getInternalPath());
tests/Drupal/Tests/Core/UrlTest.php:271:      $url->getInternalPath();
tests/Drupal/Tests/Core/UrlTest.php:272:      $url->getInternalPath();

We could also ask ourself whether this kind of method should be rather @internal

The core Path module seems to rely on having access to these internal paths for creating aliases - and unless I'm missing something, D8 Pathauto can't work with Path to make its magic happen without these internal paths, unless Path starts accepting routes and internal paths.

I agree though, without a replacement (that would be doing much the same job), I don't see why this is deprecated. It's not inconceivable to need the internal path (example: when creating aliases) and I don't see how it's doing any harm.

Possibly we need to leave this alone now.

I think it's worth exploring marking it internal instead.

Uses like this seem very hard to remove:

 \Drupal::service('path.alias_storage')->delete(array('source' => '/' . $entity->urlInfo()->getInternalPath()));

actually duplicate to #2367753: \Drupal\Core\Url::getInternalPath() cannot be deprecated