From 8894e438ce7ec4e4e60470f1b3fa34ea3e25032c Mon Sep 17 00:00:00 2001
From: Jennifer Hodgdon <yahgrp@poplarware.com>
Date: Wed, 16 Apr 2014 12:55:05 -0700
Subject: [PATCH] =?UTF-8?q?Issue=20#2238659=20by=20Jalandhar,=20G=C3=A1bor?=
 =?UTF-8?q?=20Hojtsy,=20chx:=20Clean=20up=20some=20docs=20in=20String=20st?=
 =?UTF-8?q?orage=20classes=20and=20interfaces?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../Drupal/locale/StringDatabaseStorage.php   | 54 ++++++++++---------
 .../lib/Drupal/locale/StringInterface.php     | 33 +++++-------
 .../Drupal/locale/StringStorageInterface.php  |  4 +-
 3 files changed, 42 insertions(+), 49 deletions(-)

diff --git a/core/modules/locale/lib/Drupal/locale/StringDatabaseStorage.php b/core/modules/locale/lib/Drupal/locale/StringDatabaseStorage.php
index fe87ef6437c..72d753a6f09 100644
--- a/core/modules/locale/lib/Drupal/locale/StringDatabaseStorage.php
+++ b/core/modules/locale/lib/Drupal/locale/StringDatabaseStorage.php
@@ -7,13 +7,10 @@
 
 namespace Drupal\locale;
 
-use Drupal\Core\Database\Database;
 use Drupal\Core\Database\Connection;
 
 /**
- * Defines the locale string class.
- *
- * This is the base class for SourceString and TranslationString.
+ * Defines a class to store localized strings in the database.
  */
 class StringDatabaseStorage implements StringStorageInterface {
 
@@ -32,7 +29,7 @@ class StringDatabaseStorage implements StringStorageInterface {
   protected $options = array();
 
   /**
-   * Constructs a new StringStorage controller.
+   * Constructs a new StringDatabaseStorage class.
    *
    * @param \Drupal\Core\Database\Connection $connection
    *   A Database connection to use for reading and writing configuration data.
@@ -45,21 +42,21 @@ class StringDatabaseStorage implements StringStorageInterface {
   }
 
   /**
-   * Implements Drupal\locale\StringStorageInterface::getStrings().
+   * {@inheritdoc}
    */
   public function getStrings(array $conditions = array(), array $options = array()) {
     return $this->dbStringLoad($conditions, $options, 'Drupal\locale\SourceString');
   }
 
   /**
-   * Implements Drupal\locale\StringStorageInterface::getTranslations().
+   * {@inheritdoc}
    */
   public function getTranslations(array $conditions = array(), array $options = array()) {
     return $this->dbStringLoad($conditions, array('translation' => TRUE) + $options, 'Drupal\locale\TranslationString');
   }
 
   /**
-   * Implements Drupal\locale\StringStorageInterface::findString().
+   * {@inheritdoc}
    */
   public function findString(array $conditions) {
     $values = $this->dbStringSelect($conditions)
@@ -74,7 +71,7 @@ class StringDatabaseStorage implements StringStorageInterface {
   }
 
   /**
-   * Implements Drupal\locale\StringStorageInterface::findTranslation().
+   * {@inheritdoc}
    */
   public function findTranslation(array $conditions) {
     $values = $this->dbStringSelect($conditions, array('translation' => TRUE))
@@ -90,7 +87,7 @@ class StringDatabaseStorage implements StringStorageInterface {
   }
 
   /**
-   * Implements Drupal\locale\StringStorageInterface::getLocations().
+   * {@inheritdoc}
    */
   function getLocations(array $conditions = array()) {
     $query = $this->connection->select('locales_location', 'l', $this->options)
@@ -102,21 +99,21 @@ class StringDatabaseStorage implements StringStorageInterface {
   }
 
   /**
-   * Implements Drupal\locale\StringStorageInterface::countStrings().
+   * {@inheritdoc}
    */
   public function countStrings() {
     return $this->dbExecute("SELECT COUNT(*) FROM {locales_source}")->fetchField();
   }
 
   /**
-   * Implements Drupal\locale\StringStorageInterface::countTranslations().
+   * {@inheritdoc}
    */
   public function countTranslations() {
     return $this->dbExecute("SELECT t.language, COUNT(*) AS translated FROM {locales_source} s INNER JOIN {locales_target} t ON s.lid = t.lid GROUP BY t.language")->fetchAllKeyed();
   }
 
   /**
-   * Implements Drupal\locale\StringStorageInterface::save().
+   * {@inheritdoc}
    */
   public function save($string) {
     if ($string->isNew()) {
@@ -189,7 +186,7 @@ class StringDatabaseStorage implements StringStorageInterface {
   }
 
   /**
-   * Implements Drupal\locale\StringStorageInterface::delete().
+   * {@inheritdoc}
    */
   public function delete($string) {
     if ($keys = $this->dbStringKeys($string)) {
@@ -209,7 +206,7 @@ class StringDatabaseStorage implements StringStorageInterface {
   }
 
   /**
-   * Implements Drupal\locale\StringStorageInterface::deleteLanguage().
+   * {@inheritdoc}
    */
   public function deleteStrings($conditions) {
     $lids = $this->dbStringSelect($conditions, array('fields' => array('lid')))->execute()->fetchCol();
@@ -221,21 +218,21 @@ class StringDatabaseStorage implements StringStorageInterface {
   }
 
   /**
-   * Implements Drupal\locale\StringStorageInterface::deleteLanguage().
+   * {@inheritdoc}
    */
   public function deleteTranslations($conditions) {
     $this->dbDelete('locales_target', $conditions)->execute();
   }
 
   /**
-   * Implements Drupal\locale\StringStorageInterface::createString().
+   * {@inheritdoc}
    */
   public function createString($values = array()) {
     return new SourceString($values + array('storage' => $this));
   }
 
   /**
-   * Implements Drupal\locale\StringStorageInterface::createTranslation().
+   * {@inheritdoc}
    */
   public function createTranslation($values = array()) {
     return new TranslationString($values + array(
@@ -248,11 +245,15 @@ class StringDatabaseStorage implements StringStorageInterface {
    * Gets table alias for field.
    *
    * @param string $field
-   *   Field name to find the table alias for.
+   *   One of the field names of the locales_source, locates_location,
+   *   locales_target tables to find the table alias for.
    *
    * @return string
-   *   Either 's', 't' or 'l' depending on whether the field belongs to source,
-   *   target or location table table.
+   *   One of the following values:
+   *   - 's' for "source", "context", "version" (locales_source table fields).
+   *   - 'l' for "type", "name" (locales_location table fields)
+   *   - 't' for "language", "translation", "customized" (locales_target
+   *     table fields)
    */
   protected function dbFieldTable($field) {
     if (in_array($field, array('language', 'translation', 'customized'))) {
@@ -318,13 +319,14 @@ class StringDatabaseStorage implements StringStorageInterface {
    * @param string $class
    *   Class name to use for fetching returned objects.
    *
-   * @return array
+   * @return \Drupal\locale\StringInterface[]
    *   Array of objects of the class requested.
    */
   protected function dbStringLoad(array $conditions, array $options, $class) {
     $strings = array();
     $result = $this->dbStringSelect($conditions, $options)->execute();
     foreach ($result as $item) {
+      /** @var \Drupal\locale\StringInterface $string */
       $string = new $class($item);
       $string->setStorage($this);
       $strings[] = $string;
@@ -349,7 +351,7 @@ class StringDatabaseStorage implements StringStorageInterface {
    *   these additional ones:
    *   - 'translation', Whether to include translation fields too. Defaults to
    *     FALSE.
-   * @return SelectQuery
+   * @return \Drupal\Core\Database\Query\Select
    *   Query object with all the tables, fields and conditions.
    */
   protected function dbStringSelect(array $conditions, array $options = array()) {
@@ -525,8 +527,8 @@ class StringDatabaseStorage implements StringStorageInterface {
    * @param array $keys
    *   Array with object keys indexed by field name.
    *
-   * @return DeleteQuery
-   *   Returns a new DeleteQuery object for the active database.
+   * @return \Drupal\Core\Database\Query\Delete
+   *   Returns a new Delete object for the injected database connection.
    */
   protected function dbDelete($table, $keys) {
     $query = $this->connection->delete($table, $this->options);
@@ -537,7 +539,7 @@ class StringDatabaseStorage implements StringStorageInterface {
   }
 
   /**
-   * Executes an arbitrary SELECT query string.
+   * Executes an arbitrary SELECT query string with the injected options.
    */
   protected function dbExecute($query, array $args = array()) {
     return $this->connection->query($query, $args, $this->options);
diff --git a/core/modules/locale/lib/Drupal/locale/StringInterface.php b/core/modules/locale/lib/Drupal/locale/StringInterface.php
index fb9d7eaf4f3..48e8cf86a68 100644
--- a/core/modules/locale/lib/Drupal/locale/StringInterface.php
+++ b/core/modules/locale/lib/Drupal/locale/StringInterface.php
@@ -26,8 +26,7 @@ interface StringInterface {
    * @param int $id
    *   The string identifier.
    *
-   * @return \Drupal\locale\LocaleString
-   *   The called object.
+   * @return $this
    */
   public function setId($id);
 
@@ -45,8 +44,7 @@ interface StringInterface {
    * @param string $version
    *   Version identifier.
    *
-   * @return \Drupal\locale\LocaleString
-   *   The called object.
+   * @return $this
    */
   public function setVersion($version);
 
@@ -64,9 +62,8 @@ interface StringInterface {
    * @param string $string
    *   String to set as value.
    *
-   * @return \Drupal\locale\LocaleString
-   *   The called object.
-  */
+   * @return $this
+   */
   public function setString($string);
 
   /**
@@ -85,9 +82,8 @@ interface StringInterface {
    * @param array $plurals
    *   Array of strings with plural variants.
    *
-   * @return \Drupal\locale\LocaleString
-   *   The called object.
-  */
+   * @return $this
+   */
   public function setPlurals($plurals);
 
   /**
@@ -104,9 +100,8 @@ interface StringInterface {
    * @param \Drupal\locale\StringStorageInterface $storage
    *   The storage to use for this string.
    *
-   * @return \Drupal\locale\LocaleString
-   *   The called object.
-  */
+   * @return $this
+   */
   public function setStorage($storage);
 
   /**
@@ -141,8 +136,7 @@ interface StringInterface {
    * @param bool $override
    *   (optional) Whether to override already set fields, defaults to TRUE.
    *
-   * @return \Drupal\locale\LocaleString
-   *   The called object.
+   * @return $this
    */
   public function setValues(array $values, $override = TRUE);
 
@@ -187,8 +181,7 @@ interface StringInterface {
    *   file path in case of imported strings, configuration name for strings
    *   that come from configuration, etc...
    *
-   * @return \Drupal\locale\LocaleString
-   *   The called object.
+   * @return $this
    */
   public function addLocation($type, $name);
 
@@ -208,8 +201,7 @@ interface StringInterface {
   /**
    * Saves string object to storage.
    *
-   * @return \Drupal\locale\LocaleString
-   *   The called object.
+   * @return $this
    *
    * @throws \Drupal\locale\StringStorageException
    *   In case of failures, an exception is thrown.
@@ -219,8 +211,7 @@ interface StringInterface {
   /**
    * Deletes string object from storage.
    *
-   * @return \Drupal\locale\LocaleString
-   *   The called object.
+   * @return $this
    *
    * @throws \Drupal\locale\StringStorageException
    *   In case of failures, an exception is thrown.
diff --git a/core/modules/locale/lib/Drupal/locale/StringStorageInterface.php b/core/modules/locale/lib/Drupal/locale/StringStorageInterface.php
index 2f3c1c3b5b2..3d075bf1e44 100644
--- a/core/modules/locale/lib/Drupal/locale/StringStorageInterface.php
+++ b/core/modules/locale/lib/Drupal/locale/StringStorageInterface.php
@@ -44,7 +44,7 @@ interface StringStorageInterface {
    *   (optional) An associative array of additional options. It may contain
    *   any of the options defined by getStrings().
    *
-   * @return array
+   * @return \Drupal\locale\StringInterface[]
    *   Array of \Drupal\locale\StringInterface objects matching the conditions.
    *
    * @see \Drupal\locale\StringStorageInterface::getStrings()
@@ -61,7 +61,7 @@ interface StringStorageInterface {
    *   - 'type', The location type.
    *   - 'name', The location name.
    *
-   * @return array
+   * @return \Drupal\locale\StringInterface[]
    *   Array of \Drupal\locale\StringInterface objects matching the conditions.
    *
    * @see \Drupal\locale\StringStorageInterface::getStrings()