commit 0ecdede14e19a7e134dd57823f4554dc249546ad
Author: Bart Feenstra <bart@mynameisbart.com>
Date:   Wed Mar 26 15:04:10 2014 +0100

    foo

diff --git a/core/includes/path.inc b/core/includes/path.inc
index 6186d03..ca88a97 100644
--- a/core/includes/path.inc
+++ b/core/includes/path.inc
@@ -103,7 +103,7 @@ function current_path() {
  *   A string representing the source, a number representing the pid, or an
  *   array of query conditions.
  *
- * @see \Drupal\Core\Path\Path::load()
+ * @see \Drupal\Core\Path\PathInterface::load()
  */
 function path_load($conditions) {
   if (is_numeric($conditions)) {
diff --git a/core/lib/Drupal/Core/Path/AliasManager.php b/core/lib/Drupal/Core/Path/AliasManager.php
index da3555b..0b4af2d 100644
--- a/core/lib/Drupal/Core/Path/AliasManager.php
+++ b/core/lib/Drupal/Core/Path/AliasManager.php
@@ -15,7 +15,7 @@ class AliasManager implements AliasManagerInterface {
   /**
    * The Path CRUD service.
    *
-   * @var \Drupal\Core\Path\Path
+   * @var \Drupal\Core\Path\PathInterface
    */
   protected $path;
 
@@ -74,14 +74,14 @@ class AliasManager implements AliasManagerInterface {
   /**
    * Constructs an AliasManager.
    *
-   * @param \Drupal\Core\Path\Path $path
+   * @param \Drupal\Core\Path\PathInterface $path
    *   The Path CRUD service.
    * @param \Drupal\Core\Path\AliasWhitelistInterface $whitelist
    *   The whitelist implementation to use.
    * @param \Drupal\Core\Language\LanguageManager $language_manager
    *   The language manager.
    */
-  public function __construct(Path $path, AliasWhitelistInterface $whitelist, LanguageManager $language_manager) {
+  public function __construct(PathInterface $path, AliasWhitelistInterface $whitelist, LanguageManager $language_manager) {
     $this->path = $path;
     $this->languageManager = $language_manager;
     $this->whitelist = $whitelist;
diff --git a/core/lib/Drupal/Core/Path/Path.php b/core/lib/Drupal/Core/Path/Path.php
index 6802030..1d7c684 100644
--- a/core/lib/Drupal/Core/Path/Path.php
+++ b/core/lib/Drupal/Core/Path/Path.php
@@ -2,7 +2,7 @@
 
 /**
  * @file
- * Contains Drupal\Core\Path\Path.
+ * Contains \Drupal\Core\Path\Path.
  */
 
 namespace Drupal\Core\Path;
@@ -12,9 +12,9 @@
 use Drupal\Core\Language\Language;
 
 /**
- * Defines a class for CRUD operations on path aliases.
+ * Provides a class for CRUD operations on path aliases.
  */
-class Path {
+class Path implements PathInterface {
 
   /**
    * The database connection.
@@ -45,27 +45,7 @@ public function __construct(Connection $connection, ModuleHandlerInterface $modu
   }
 
   /**
-   * Saves a path alias to the database.
-   *
-   * @param string $source
-   *   The internal system path.
-   *
-   * @param string $alias
-   *   The URL alias.
-   *
-   * @param string $langcode
-   *   The language code of the alias.
-   *
-   * @param int $pid
-   *   Unique path alias identifier.
-   *
-   * @return
-   *   FALSE if the path could not be saved or an associative array containing
-   *   the following keys:
-   *   - source: The internal system path.
-   *   - alias: The URL alias.
-   *   - pid: Unique path alias identifier.
-   *   - langcode: The language code of the alias.
+   * {@inheritdoc}
    */
   public function save($source, $alias, $langcode = Language::LANGCODE_NOT_SPECIFIED, $pid = NULL) {
 
@@ -100,18 +80,7 @@ public function save($source, $alias, $langcode = Language::LANGCODE_NOT_SPECIFI
   }
 
   /**
-   * Fetches a specific URL alias from the database.
-   *
-   * @param $conditions
-   *   An array of query conditions.
-   *
-   * @return
-   *   FALSE if no alias was found or an associative array containing the
-   *   following keys:
-   *   - source: The internal system path.
-   *   - alias: The URL alias.
-   *   - pid: Unique path alias identifier.
-   *   - langcode: The language code of the alias.
+   * {@inheritdoc}
    */
   public function load($conditions) {
     $select = $this->connection->select('url_alias');
@@ -125,10 +94,7 @@ public function load($conditions) {
   }
 
   /**
-   * Deletes a URL alias.
-   *
-   * @param array $conditions
-   *   An array of criteria.
+   * {@inheritdoc}
    */
   public function delete($conditions) {
     $path = $this->load($conditions);
@@ -143,15 +109,7 @@ public function delete($conditions) {
   }
 
   /**
-   * Preloads path alias information for a given list of source paths.
-   *
-   * @param $path
-   *   The path to investigate for corresponding aliases.
-   * @param $langcode
-   *   Language code to search the path with. If there's no path defined for
-   *   that language it will search paths without language.
-   * @return array
-   *   Source (keys) to alias (values) mapping.
+   * {@inheritdoc}
    */
   public function preloadPathAlias($preloaded, $langcode) {
     $args = array(
@@ -182,16 +140,7 @@ public function preloadPathAlias($preloaded, $langcode) {
   }
 
   /**
-   * Returns an alias of Drupal system URL.
-   *
-   * @param string $path
-   *   The path to investigate for corresponding path aliases.
-   * @param string $langcode
-   *   Language code to search the path with. If there's no path defined for
-   *   that language it will search paths without language.
-   *
-   * @return string|bool
-   *   A path alias, or FALSE if no path was found.
+   * {@inheritdoc}
    */
   public function lookupPathAlias($path, $langcode) {
     $args = array(
@@ -215,16 +164,7 @@ public function lookupPathAlias($path, $langcode) {
   }
 
   /**
-   * Returns Drupal system URL of an alias.
-   *
-   * @param string $path
-   *   The path to investigate for corresponding system URLs.
-   * @param string $langcode
-   *   Language code to search the path with. If there's no path defined for
-   *   that language it will search paths without language.
-   *
-   * @return string|bool
-   *   A Drupal system path, or FALSE if no path was found.
+   * {@inheritdoc}
    */
   public function lookupPathSource($path, $langcode) {
     $args = array(
diff --git a/core/lib/Drupal/Core/Path/PathInterface.php b/core/lib/Drupal/Core/Path/PathInterface.php
new file mode 100644
index 0000000..8d6cfef
--- /dev/null
+++ b/core/lib/Drupal/Core/Path/PathInterface.php
@@ -0,0 +1,103 @@
+<?php
+
+/**
+ * @file
+ * Contains \Drupal\Core\Path\PathInterface.
+ */
+
+namespace Drupal\Core\Path;
+
+use Drupal\Core\Language\Language;
+
+/**
+ * Provides a class for CRUD operations on path aliases.
+ */
+interface PathInterface {
+
+  /**
+   * Saves a path alias to the database.
+   *
+   * @param string $source
+   *   The internal system path.
+   * @param string $alias
+   *   The URL alias.
+   * @param string $langcode
+   *   The language code of the alias.
+   * @param int|null $pid
+   *   Unique path alias identifier.
+   *
+   * @return mixed[]|bool
+   *   FALSE if the path could not be saved or an associative array containing
+   *   the following keys:
+   *   - source (string): The internal system path.
+   *   - alias (string): The URL alias.
+   *   - pid (int): Unique path alias identifier.
+   *   - langcode (string): The language code of the alias.
+   */
+  public function save($source, $alias, $langcode = Language::LANGCODE_NOT_SPECIFIED, $pid = NULL);
+
+  /**
+   * Fetches a specific URL alias from the database.
+   *
+   * @param $conditions
+   *   An array of query conditions.
+   *
+   * @return mixed[]|bool
+   *   FALSE if no alias was found or an associative array containing the
+   *   following keys:
+   *   - source (string): The internal system path.
+   *   - alias (string): The URL alias.
+   *   - pid (int): Unique path alias identifier.
+   *   - langcode (string): The language code of the alias.
+   */
+  public function load($conditions);
+
+  /**
+   * Deletes a URL alias.
+   *
+   * @param array $conditions
+   *   An array of criteria.
+   */
+  public function delete($conditions);
+
+  /**
+   * Pre-loads path alias information for a given list of source paths.
+   *
+   * @param $preloaded
+   * @param $langcode
+   *   Language code to search the path with. If there's no path defined for
+   *   that language it will search paths without language.
+   *
+   * @return string[]
+   *   Source (keys) to alias (values) mapping.
+   */
+  public function preloadPathAlias($preloaded, $langcode);
+
+  /**
+   * Returns an alias of Drupal system URL.
+   *
+   * @param string $path
+   *   The path to investigate for corresponding path aliases.
+   * @param string $langcode
+   *   Language code to search the path with. If there's no path defined for
+   *   that language it will search paths without language.
+   *
+   * @return string|false
+   *   A path alias, or FALSE if no path was found.
+   */
+  public function lookupPathAlias($path, $langcode);
+
+  /**
+   * Returns Drupal system URL of an alias.
+   *
+   * @param string $path
+   *   The path to investigate for corresponding system URLs.
+   * @param string $langcode
+   *   Language code to search the path with. If there's no path defined for
+   *   that language it will search paths without language.
+   *
+   * @return string|false
+   *   A Drupal system path, or FALSE if no path was found.
+   */
+  public function lookupPathSource($path, $langcode);
+}
diff --git a/core/modules/migrate/lib/Drupal/migrate/Plugin/migrate/destination/UrlAlias.php b/core/modules/migrate/lib/Drupal/migrate/Plugin/migrate/destination/UrlAlias.php
index e2c1403..4419a0e 100644
--- a/core/modules/migrate/lib/Drupal/migrate/Plugin/migrate/destination/UrlAlias.php
+++ b/core/modules/migrate/lib/Drupal/migrate/Plugin/migrate/destination/UrlAlias.php
@@ -38,7 +38,7 @@ class UrlAlias extends DestinationBase implements ContainerFactoryPluginInterfac
    *   The plugin implementation definition.
    * @param MigrationInterface $migration
    *   The migration.
-   * @param \Drupal\Core\Path\Path $path
+   * @param \Drupal\Core\Path\PathInterface $path
    *   The path crud service.
    */
   public function __construct(array $configuration, $plugin_id, array $plugin_definition, MigrationInterface $migration, Path $path) {
diff --git a/core/modules/path/lib/Drupal/path/Form/DeleteForm.php b/core/modules/path/lib/Drupal/path/Form/DeleteForm.php
index 9c84de8..c6d3e6d 100644
--- a/core/modules/path/lib/Drupal/path/Form/DeleteForm.php
+++ b/core/modules/path/lib/Drupal/path/Form/DeleteForm.php
@@ -8,7 +8,7 @@
 namespace Drupal\path\Form;
 
 use Drupal\Core\Form\ConfirmFormBase;
-use Drupal\Core\Path\Path;
+use Drupal\Core\Path\PathInterface;
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
@@ -19,7 +19,7 @@ class DeleteForm extends ConfirmFormBase {
   /**
    * The path crud service.
    *
-   * @var Path $path
+   * @var PathInterface $path
    */
   protected $path;
 
@@ -31,12 +31,12 @@ class DeleteForm extends ConfirmFormBase {
   protected $pathAlias;
 
   /**
-   * Constructs a \Drupal\Core\Path\Path object.
+   * Constructs a \Drupal\path\Form\DeleteForm object.
    *
-   * @param \Drupal\Core\Path\Path $path
+   * @param \Drupal\Core\Path\PathInterface $path
    *   The path crud service.
    */
-  public function __construct(Path $path) {
+  public function __construct(PathInterface $path) {
     $this->path = $path;
   }
 
diff --git a/core/modules/path/path.api.php b/core/modules/path/path.api.php
index c69b97d..478fc6f 100644
--- a/core/modules/path/path.api.php
+++ b/core/modules/path/path.api.php
@@ -13,14 +13,11 @@
 /**
  * Respond to a path being inserted.
  *
- * @param $path
- *   An associative array containing the following keys:
- *   - source: The internal system path.
- *   - alias: The URL alias.
- *   - pid: Unique path alias identifier.
- *   - langcode: The language code of the alias.
+ * @param array $path
+ *   The array structure is identical to that of the return value of
+ *   \Drupal\Core\Path\PathInterface::save().
  *
- * @see \Drupal\Core\Path\Path::save()
+ * @see \Drupal\Core\Path\PathInterface::save()
  */
 function hook_path_insert($path) {
   db_insert('mytable')
@@ -35,13 +32,10 @@ function hook_path_insert($path) {
  * Respond to a path being updated.
  *
  * @param $path
- *   An associative array containing the following keys:
- *   - source: The internal system path.
- *   - alias: The URL alias.
- *   - pid: Unique path alias identifier.
- *   - langcode: The language code of the alias.
+ *   The array structure is identical to that of the return value of
+ *   \Drupal\Core\Path\PathInterface::save().
  *
- * @see \Drupal\Core\Path\Path::save()
+ * @see \Drupal\Core\Path\PathInterface::save()
  */
 function hook_path_update($path) {
   db_update('mytable')
@@ -54,13 +48,10 @@ function hook_path_update($path) {
  * Respond to a path being deleted.
  *
  * @param $path
- *   An associative array containing the following keys:
- *   - source: The internal system path.
- *   - alias: The URL alias.
- *   - pid: Unique path alias identifier.
- *   - langcode: The language code of the alias.
+ *   The array structure is identical to that of the return value of
+ *   \Drupal\Core\Path\PathInterface::save().
  *
- * @see \Drupal\Core\Path\Path::delete()
+ * @see \Drupal\Core\Path\PathInterface::delete()
  */
 function hook_path_delete($path) {
   db_delete('mytable')