Update to Drupal 8.1.0. For more information, see https://www.drupal.org/drupal-8.1.0-release-notes

vendor/symfony/translation/Catalogue/AbstractOperation.php

@@ -17,38 +17,60 @@ use Symfony\Component\Translation\MessageCatalogueInterface;
 /**
  * Base catalogues binary operation class.
  *
+ * A catalogue binary operation performs operation on
+ * source (the left argument) and target (the right argument) catalogues.
+ *
  * @author Jean-François Simon <contact@jfsimon.fr>
  */
 abstract class AbstractOperation implements OperationInterface
 {
     /**
-     * @var MessageCatalogueInterface
+     * @var MessageCatalogueInterface The source catalogue
      */
     protected $source;
 
     /**
-     * @var MessageCatalogueInterface
+     * @var MessageCatalogueInterface The target catalogue
      */
     protected $target;
 
     /**
-     * @var MessageCatalogue
+     * @var MessageCatalogue The result catalogue
      */
     protected $result;
 
     /**
-     * @var null|array
+     * @var null|array The domains affected by this operation
      */
     private $domains;
 
     /**
-     * @var array
+     * This array stores 'all', 'new' and 'obsolete' messages for all valid domains.
+     *
+     * The data structure of this array is as follows:
+     * ```php
+     * array(
+     *     'domain 1' => array(
+     *         'all' => array(...),
+     *         'new' => array(...),
+     *         'obsolete' => array(...)
+     *     ),
+     *     'domain 2' => array(
+     *         'all' => array(...),
+     *         'new' => array(...),
+     *         'obsolete' => array(...)
+     *     ),
+     *     ...
+     * )
+     * ```
+     *
+     * @var array The array that stores 'all', 'new' and 'obsolete' messages
      */
     protected $messages;
 
     /**
-     * @param MessageCatalogueInterface $source
-     * @param MessageCatalogueInterface $target
+     * @param MessageCatalogueInterface $source The source catalogue
+     * @param MessageCatalogueInterface $target The target catalogue
      *
      * @throws \LogicException
      */
@@ -140,7 +162,10 @@ abstract class AbstractOperation implements OperationInterface
     }
 
     /**
-     * @param string $domain
+     * Performs operation on source and target catalogues for the given domain and
+     * stores the results.
+     *
+     * @param string $domain The domain which the operation will be performed for
      */
     abstract protected function processDomain($domain);
 }

vendor/symfony/translation/Catalogue/DiffOperation.php

@@ -11,45 +11,23 @@
 
 namespace Symfony\Component\Translation\Catalogue;
 
+@trigger_error('The '.__NAMESPACE__.'\DiffOperation class is deprecated since version 2.8 and will be removed in 3.0. Use the TargetOperation class in the same namespace instead.', E_USER_DEPRECATED);
+
 /**
  * Diff operation between two catalogues.
  *
+ * The name of 'Diff' is misleading because the operation
+ * has nothing to do with diff:
+ *
+ * intersection = source ∩ target = {x: x ∈ source ∧ x ∈ target}
+ * all = intersection ∪ (target ∖ intersection) = target
+ * new = all ∖ source = {x: x ∈ target ∧ x ∉ source}
+ * obsolete = source ∖ all = source ∖ target = {x: x ∈ source ∧ x ∉ target}
+ *
  * @author Jean-François Simon <contact@jfsimon.fr>
+ *
+ * @deprecated since version 2.8, to be removed in 3.0. Use TargetOperation instead.
  */
-class DiffOperation extends AbstractOperation
+class DiffOperation extends TargetOperation
 {
-    /**
-     * {@inheritdoc}
-     */
-    protected function processDomain($domain)
-    {
-        $this->messages[$domain] = array(
-            'all' => array(),
-            'new' => array(),
-            'obsolete' => array(),
-        );
-
-        foreach ($this->source->all($domain) as $id => $message) {
-            if ($this->target->has($id, $domain)) {
-                $this->messages[$domain]['all'][$id] = $message;
-                $this->result->add(array($id => $message), $domain);
-                if (null !== $keyMetadata = $this->source->getMetadata($id, $domain)) {
-                    $this->result->setMetadata($id, $keyMetadata, $domain);
-                }
-            } else {
-                $this->messages[$domain]['obsolete'][$id] = $message;
-            }
-        }
-
-        foreach ($this->target->all($domain) as $id => $message) {
-            if (!$this->source->has($id, $domain)) {
-                $this->messages[$domain]['all'][$id] = $message;
-                $this->messages[$domain]['new'][$id] = $message;
-                $this->result->add(array($id => $message), $domain);
-                if (null !== $keyMetadata = $this->target->getMetadata($id, $domain)) {
-                    $this->result->setMetadata($id, $keyMetadata, $domain);
-                }
-            }
-        }
-    }
 }

vendor/symfony/translation/Catalogue/MergeOperation.php

@@ -12,7 +12,11 @@
 namespace Symfony\Component\Translation\Catalogue;
 
 /**
- * Merge operation between two catalogues.
+ * Merge operation between two catalogues as follows:
+ * all = source ∪ target = {x: x ∈ source ∨ x ∈ target}
+ * new = all ∖ source = {x: x ∈ target ∧ x ∉ source}
+ * obsolete = source ∖ all = {x: x ∈ source ∧ x ∉ source ∧ x ∉ target} = ∅
+ * Basically, the result contains messages from both catalogues.
  *
  * @author Jean-François Simon <contact@jfsimon.fr>
  */

vendor/symfony/translation/Catalogue/OperationInterface.php

@@ -16,6 +16,20 @@ use Symfony\Component\Translation\MessageCatalogueInterface;
 /**
  * Represents an operation on catalogue(s).
  *
+ * An instance of this interface performs an operation on one or more catalogues and
+ * stores intermediate and final results of the operation.
+ *
+ * The first catalogue in its argument(s) is called the 'source catalogue' or 'source' and
+ * the following results are stored:
+ *
+ * Messages: also called 'all', are valid messages for the given domain after the operation is performed.
+ *
+ * New Messages: also called 'new' (new = all ∖ source = {x: x ∈ all ∧ x ∉ source}).
+ *
+ * Obsolete Messages: also called 'obsolete' (obsolete = source ∖ all = {x: x ∈ source ∧ x ∉ all}).
+ *
+ * Result: also called 'result', is the resulting catalogue for the given domain that holds the same messages as 'all'.
+ *
  * @author Jean-François Simon <jeanfrancois.simon@sensiolabs.com>
  */
 interface OperationInterface
@@ -28,7 +42,7 @@ interface OperationInterface
     public function getDomains();
 
     /**
-     * Returns all valid messages after operation.
+     * Returns all valid messages ('all') after operation.
      *
      * @param string $domain
      *
@@ -37,7 +51,7 @@ interface OperationInterface
     public function getMessages($domain);
 
     /**
-     * Returns new messages after operation.
+     * Returns new messages ('new') after operation.
      *
      * @param string $domain
      *
@@ -46,7 +60,7 @@ interface OperationInterface
     public function getNewMessages($domain);
 
     /**
-     * Returns obsolete messages after operation.
+     * Returns obsolete messages ('obsolete') after operation.
      *
      * @param string $domain
      *
@@ -55,7 +69,7 @@ interface OperationInterface
     public function getObsoleteMessages($domain);
 
     /**
-     * Returns resulting catalogue.
+     * Returns resulting catalogue ('result').
      *
      * @return MessageCatalogueInterface
      */

vendor/symfony/translation/Catalogue/TargetOperation.php

@@ -0,0 +1,69 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Translation\Catalogue;
+
+/**
+ * Target operation between two catalogues:
+ * intersection = source ∩ target = {x: x ∈ source ∧ x ∈ target}
+ * all = intersection ∪ (target ∖ intersection) = target
+ * new = all ∖ source = {x: x ∈ target ∧ x ∉ source}
+ * obsolete = source ∖ all = source ∖ target = {x: x ∈ source ∧ x ∉ target}
+ * Basically, the result contains messages from the target catalogue. 
+ *
+ * @author Michael Lee <michael.lee@zerustech.com>
+ */
+class TargetOperation extends AbstractOperation
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function processDomain($domain)
+    {
+        $this->messages[$domain] = array(
+            'all' => array(),
+            'new' => array(),
+            'obsolete' => array(),
+        );
+
+        // For 'all' messages, the code can't be simplified as ``$this->messages[$domain]['all'] = $target->all($domain);``, 
+        // because doing so will drop messages like {x: x ∈ source ∧ x ∉ target.all ∧ x ∈ target.fallback}
+        //
+        // For 'new' messages, the code can't be simplied as ``array_diff_assoc($this->target->all($domain), $this->source->all($domain));``
+        // because doing so will not exclude messages like {x: x ∈ target ∧ x ∉ source.all ∧ x ∈ source.fallback}
+        // 
+        // For 'obsolete' messages, the code can't be simplifed as ``array_diff_assoc($this->source->all($domain), $this->target->all($domain))``
+        // because doing so will not exclude messages like {x: x ∈ source ∧ x ∉ target.all ∧ x ∈ target.fallback}
+
+        foreach ($this->source->all($domain) as $id => $message) {
+            if ($this->target->has($id, $domain)) {
+                $this->messages[$domain]['all'][$id] = $message;
+                $this->result->add(array($id => $message), $domain);
+                if (null !== $keyMetadata = $this->source->getMetadata($id, $domain)) {
+                    $this->result->setMetadata($id, $keyMetadata, $domain);
+                }
+            } else {
+                $this->messages[$domain]['obsolete'][$id] = $message;
+            }
+        }
+
+        foreach ($this->target->all($domain) as $id => $message) {
+            if (!$this->source->has($id, $domain)) {
+                $this->messages[$domain]['all'][$id] = $message;
+                $this->messages[$domain]['new'][$id] = $message;
+                $this->result->add(array($id => $message), $domain);
+                if (null !== $keyMetadata = $this->target->getMetadata($id, $domain)) {
+                    $this->result->setMetadata($id, $keyMetadata, $domain);
+                }
+            }
+        }
+    }
+}