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

composer.lock

@@ -2627,23 +2627,23 @@
         },
         {
             "name": "jcalderonzumba/mink-phantomjs-driver",
-            "version": "dev-master",
+            "version": "v0.3.1",
             "source": {
                 "type": "git",
                 "url": "https://github.com/jcalderonzumba/MinkPhantomJSDriver.git",
-                "reference": "10d7c48c9a4129463052321b52450d98983c4332"
+                "reference": "782892dbea4af7d04024374672b3790b6c008def"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/jcalderonzumba/MinkPhantomJSDriver/zipball/10d7c48c9a4129463052321b52450d98983c4332",
+                "url": "https://api.github.com/repos/jcalderonzumba/MinkPhantomJSDriver/zipball/782892dbea4af7d04024374672b3790b6c008def",
-                "reference": "10d7c48c9a4129463052321b52450d98983c4332",
+                "reference": "782892dbea4af7d04024374672b3790b6c008def",
                 "shasum": ""
             },
             "require": {
                 "behat/mink": "~1.6",
                 "jcalderonzumba/gastonjs": "~1.0",
                 "php": ">=5.4",
-                "twig/twig": "~1.8"
+                "twig/twig": "~1.20|~2.0"
             },
             "require-dev": {
                 "phpunit/phpunit": "~4.6",
@@ -2684,7 +2684,7 @@
                 "phantomjs",
                 "testing"
             ],
-            "time": "2015-10-05 18:24:44"
+            "time": "2015-12-04 13:55:02"
         },
         {
             "name": "mikey179/vfsStream",
@@ -3740,39 +3740,7 @@
     "aliases": [],
     "minimum-stability": "dev",
     "stability-flags": {
-        "php": 0,
+        "jcalderonzumba/gastonjs": 20
-        "symfony/class-loader": 0,
-        "symfony/console": 0,
-        "symfony/dependency-injection": 0,
-        "symfony/event-dispatcher": 0,
-        "symfony/http-foundation": 0,
-        "symfony/http-kernel": 0,
-        "symfony/routing": 0,
-        "symfony/serializer": 0,
-        "symfony/translation": 0,
-        "symfony/validator": 0,
-        "symfony/process": 0,
-        "symfony/yaml": 0,
-        "twig/twig": 0,
-        "doctrine/common": 0,
-        "doctrine/annotations": 0,
-        "guzzlehttp/guzzle": 0,
-        "symfony-cmf/routing": 0,
-        "easyrdf/easyrdf": 0,
-        "zendframework/zend-feed": 0,
-        "stack/builder": 0,
-        "egulias/email-validator": 0,
-        "masterminds/html5": 0,
-        "symfony/psr-http-message-bridge": 0,
-        "zendframework/zend-diactoros": 0,
-        "composer/semver": 0,
-        "behat/mink": 0,
-        "behat/mink-goutte-driver": 0,
-        "jcalderonzumba/gastonjs": 20,
-        "jcalderonzumba/mink-phantomjs-driver": 20,
-        "mikey179/vfsstream": 0,
-        "phpunit/phpunit": 0,
-        "symfony/css-selector": 0
     },
     "prefer-stable": true,
     "prefer-lowest": false,

core/CHANGELOG.txt

@@ -341,7 +341,7 @@ Drupal 7.0, 2011-01-05
 - Improved time zone support:
     * Drupal now uses PHP's time zone database when rendering dates in local
       time. Site-wide and user-configured time zone offsets have been converted
-      to time zone names, e.g. Africa/Abidjan.
+      to time zone names; for example, Africa/Abidjan.
     * In some cases the upgrade and install scripts do not choose the preferred
       site default time zone. The automatically-selected time zone can be
       corrected at admin/config/regional/settings.
@@ -399,7 +399,7 @@ Drupal 7.0, 2011-01-05
       preserved but renamed to file_unmanaged_*().
     * Rewrote file handling to use PHP stream wrappers to enable support for
       both public and private files and to support pluggable storage mechanisms
-      and access to remote resources (e.g. S3 storage or Flickr photos).
+      and access to remote resources (for example, S3 storage or Flickr photos).
     * The mime_extension_mapping variable has been removed. Modules that need to
       alter the default MIME type extension mappings should implement
       hook_file_mimetype_mapping_alter().
@@ -816,7 +816,7 @@ Drupal 4.7.0, 2006-05-01
 - Added support for PHP5's 'mysqli' extension.
 - Search module:
     * Made indexer smarter and more robust.
-    * Added advanced search operators (e.g., phrase, node type, etc.).
+    * Added advanced search operators (phrase, node type, etc.).
     * Added customizable result ranking.
 - PostgreSQL support:
     * Removed dependency on PL/pgSQL procedural language.

core/MAINTAINERS.txt

@@ -87,7 +87,6 @@ Cron system
 
 CSS
 - John Albin Wilkins 'JohnAlbin' https://www.drupal.org/u/johnalbin
-- Lewis Nyman 'LewisNyman' https://www.drupal.org/u/lewisnyman
 
 Database system
 - Larry Garfield 'Crell' https://www.drupal.org/u/crell
@@ -486,7 +485,10 @@ Classy theme
 - Morten Birch Heide-Jørgensen 'mortendk' https://www.drupal.org/u/mortendk
 
 Seven theme
-- Lewis Nyman 'LewisNyman' https://www.drupal.org/u/lewisnyman
+- ?
+
+Stable theme
+- Scott Reeves 'Cottser' https://www.drupal.org/u/cottser
 
 Stark theme
 - John Albin Wilkins 'JohnAlbin' https://www.drupal.org/u/johnalbin

core/composer.json

@@ -35,7 +35,7 @@
     "behat/mink": "~1.6",
     "behat/mink-goutte-driver": "~1.2",
     "jcalderonzumba/gastonjs": "^1.1@dev",
-    "jcalderonzumba/mink-phantomjs-driver": "dev-master#10d7c48c9a4129463052321b52450d98983c4332",
+    "jcalderonzumba/mink-phantomjs-driver": "~0.3.1",
     "mikey179/vfsStream": "~1.2",
     "phpunit/phpunit": "~4.8",
     "symfony/css-selector": "2.7.*"

core/config/schema/core.data_types.schema.yml

@@ -87,12 +87,22 @@ color_hex:
 # Complex extended data types:
 
 # Root of a configuration object.
+
+_core_config_info:
+  type: mapping
+  mapping:
+    default_config_hash:
+      type: string
+      label: 'Default configuration hash'
+
 config_object:
   type: mapping
   mapping:
     langcode:
       type: string
       label: 'Language code'
+    _core:
+      type: _core_config_info
 
 # Mail text with subject and body parts.
 mail:
@@ -281,6 +291,8 @@ config_entity:
       label: 'Third party settings'
       sequence:
         type: '[%parent.%parent.%type].third_party.[%key]'
+    _core:
+      type: _core_config_info
 
 block_settings:
   type: mapping

core/core.api.php

@@ -344,7 +344,7 @@
  *   Configuration entity classes expose dependencies by overriding the
  *   \Drupal\Core\Config\Entity\ConfigEntityInterface::calculateDependencies()
  *   method.
- * - On routes for paths staring with '/admin' or otherwise designated as
+ * - On routes for paths starting with '/admin' or otherwise designated as
  *   administration paths (such as node editing when it is set as an admin
  *   operation), if they have configuration entity placeholders, configuration
  *   entities are normally loaded in their original language, without
@@ -567,7 +567,7 @@
  *
  * By default cached data is stored in the database. This can be configured
  * though so that all cached data, or that of an individual cache bin, uses a
- * different cache backend, such as APC or Memcache, for storage.
+ * different cache backend, such as APCu or Memcache, for storage.
  *
  * In a settings.php file, you can override the service used for a particular
  * cache bin. For example, if your service implementation of
@@ -692,7 +692,7 @@
  * "service" (such as accessing the database, sending email, or translating user
  * interface text) is defined (given a name and an interface or at least a
  * class that defines the methods that may be called), and a default class is
- * defined to provide the service. These two steps must be done together, and
+ * designated to provide the service. These two steps must be done together, and
  * can be done by Drupal Core or a module. Other modules can then define
  * alternative classes to provide the same services, overriding the default
  * classes. Classes and functions that need to use the service should always
@@ -843,6 +843,32 @@
  * @}
  */
 
+/**
+ * @defgroup listing_page_service Page header for Services page
+ * @{
+ * Introduction to services
+ *
+ * A "service" (such as accessing the database, sending email, or translating
+ * user interface text) can be defined by a module or Drupal core. Defining a
+ * service means giving it a name and designating a default class to provide the
+ * service; ideally, there should also be an interface that defines the methods
+ * that may be called. Services are collected into the Dependency Injection
+ * Container, and can be overridden to use different classes or different
+ * instantiation by modules. See the
+ * @link container Services and Dependency Injection Container topic @endlink
+ * for details.
+ *
+ * Some services have tags, which are defined in the service definition. Tags
+ * are used to define a group of related services, or to specify some aspect of
+ * how the service behaves. See the
+ * @link service_tag Service Tags topic @endlink for more information.
+ *
+ * @see container
+ * @see service_tag
+ *
+ * @}
+ */
+
 /**
  * @defgroup typed_data Typed Data API
  * @{
@@ -1441,6 +1467,38 @@
  * @}
  */
 
+/**
+ * @defgroup listing_page_class Page header for Classes page
+ * @{
+ * Introduction to classes
+ *
+ * A lot of the PHP code in Drupal is object oriented (OO), making use of
+ * @link http://php.net/manual/language.oop5.php PHP classes, interfaces, and traits. @endlink
+ * See the
+ * @link oo_conventions Objected-oriented programming conventions @endlink
+ * for more information.
+ *
+ * @see oo_conventions
+ *
+ * @}
+ */
+
+/**
+ * @defgroup listing_page_namespace Page header for Namespaces page
+ * @{
+ * Introduction to namespaces
+ *
+ * PHP classes, interfaces, and traits in Drupal are
+ * @link http://php.net/manual/en/language.namespaces.rationale.php namespaced. @endlink
+ * See the
+ * @link oo_conventions Objected-oriented programming conventions @endlink
+ * for more information.
+ *
+ * @see oo_conventions
+ *
+ * @}
+ */
+
 /**
  * @defgroup best_practices Best practices for developers
  * @{
@@ -1667,16 +1725,13 @@
  *     _form: '\Drupal\mymodule\Form\ExampleForm'
  * @endcode
  *
- * The $form argument to form-related functions is a structured array containing
+ * The $form argument to form-related functions is a specialized render array
- * the elements and properties of the form. For information on the array
+ * containing the elements and properties of the form. For more about render
- * components and format, and more detailed explanations of the Form API
+ * arrays, see the @link theme_render Render API topic. @endlink For more
- * workflow, see the
+ * detailed explanations of the Form API workflow, see the
- * @link forms_api_reference.html Form API reference @endlink
- * and the
  * @link https://www.drupal.org/node/2117411 Form API documentation section. @endlink
- * In addition, there is a set of Form API tutorials in
+ * In addition, there is a set of Form API tutorials in the
- * @link form_example_tutorial.inc the Form Example Tutorial @endlink which
+ * @link https://www.drupal.org/project/examples Examples for Developers project. @endlink
- * provide basics all the way up through multistep forms.
  *
  * In the form builder, validation, submission, and other form methods,
  * $form_state is the primary influence on the processing of the form and is

core/includes/batch.inc

@@ -203,7 +203,7 @@ function _batch_progress_page() {
  * exceeded. It will continue with the next operation of the same batch set in
  * the next request.
  *
- * @return
+ * @return array
  *   An array containing a completion value (in percent) and a status message.
  */
 function _batch_process() {
@@ -337,15 +337,15 @@ function _batch_process() {
 /**
  * Formats the percent completion for a batch set.
  *
- * @param $total
+ * @param int $total
  *   The total number of operations.
- * @param $current
+ * @param int|float $current
  *   The number of the current operation. This may be a floating point number
  *   rather than an integer in the case of a multi-step operation that is not
  *   yet complete; in that case, the fractional part of $current represents the
  *   fraction of the operation that has been completed.
  *
- * @return
+ * @return string
  *   The properly formatted percentage, as a string. We output percentages
  *   using the correct number of decimal places so that we never print "100%"
  *   until we are finished, but we also never print more decimal places than
@@ -372,8 +372,9 @@ function &_batch_current_set() {
  * process and execute its form submit handler (if defined), which may add
  * further sets to this batch.
  *
- * @return
+ * @return true|null
- *   TRUE if a subsequent set was found in the batch.
+ *   TRUE if a subsequent set was found in the batch; no value will be returned
+ *   if no subsequent set was found.
  */
 function _batch_next_set() {
   $batch = &batch_get();

core/includes/database.inc

@@ -32,8 +32,8 @@ use Drupal\Core\Site\Settings;
  *   The prepared statement query to run. Although it will accept both named and
  *   unnamed placeholders, named placeholders are strongly preferred as they are
  *   more self-documenting. If the argument corresponding to a placeholder is
- *   an array of values to be expanded, e.g. for an IN query, the placeholder
+ *   an array of values to be expanded (for example, with an IN query), the
- *   should be named with a trailing bracket like :example[]
+ *   placeholder should be named with a trailing bracket like :example[].
  * @param array $args
  *   An array of values to substitute into the query. If the query uses named
  *   placeholders, this is an associative array in any order. If the query uses
@@ -47,7 +47,7 @@ use Drupal\Core\Site\Settings;
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call query() on it. E.g.
+ *   call query() on it. For example,
  *   $injected_database->query($query, $args, $options);
  *
  * @see \Drupal\Core\Database\Connection::query()
@@ -85,7 +85,7 @@ function db_query($query, array $args = array(), array $options = array()) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call queryRange() on it. E.g.
+ *   call queryRange() on it. For example,
  *   $injected_database->queryRange($query, $from, $count, $args, $options);
  *
  * @see \Drupal\Core\Database\Connection::queryRange()
@@ -121,7 +121,7 @@ function db_query_range($query, $from, $count, array $args = array(), array $opt
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call queryTemporary() on it. E.g.
+ *   call queryTemporary() on it. For example,
  *   $injected_database->queryTemporary($query, $args, $options);
  *
  * @see \Drupal\Core\Database\Connection::queryTemporary()
@@ -148,7 +148,8 @@ function db_query_temporary($query, array $args = array(), array $options = arra
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call insert() on it. E.g. $injected_database->insert($table, $options);
+ *   call insert() on it. For example,
+ *   $injected_database->insert($table, $options);
  *
  * @see \Drupal\Core\Database\Connection::insert()
  * @see \Drupal\Core\Database\Connection::defaultOptions()
@@ -173,7 +174,8 @@ function db_insert($table, array $options = array()) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call merge() on it. E.g. $injected_database->merge($table, $options);
+ *   call merge() on it. For example,
+ *   $injected_database->merge($table, $options);
  *
  * @see \Drupal\Core\Database\Connection::merge()
  * @see \Drupal\Core\Database\Connection::defaultOptions()
@@ -198,7 +200,8 @@ function db_merge($table, array $options = array()) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call update() on it. E.g. $injected_database->update($table, $options);
+ *   call update() on it. For example,
+ *   $injected_database->update($table, $options);
  *
  * @see \Drupal\Core\Database\Connection::update()
  * @see \Drupal\Core\Database\Connection::defaultOptions()
@@ -223,7 +226,8 @@ function db_update($table, array $options = array()) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call delete() on it. E.g. $injected_database->delete($table, $options);
+ *   call delete() on it. For example,
+ *   $injected_database->delete($table, $options);
  *
  * @see \Drupal\Core\Database\Connection::delete()
  * @see \Drupal\Core\Database\Connection::defaultOptions()
@@ -248,7 +252,8 @@ function db_delete($table, array $options = array()) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call truncate() on it. E.g. $injected_database->truncate($table, $options);
+ *   call truncate() on it. For example,
+ *   $injected_database->truncate($table, $options);
  *
  * @see \Drupal\Core\Database\Connection::truncate()
  * @see \Drupal\Core\Database\Connection::defaultOptions()
@@ -277,7 +282,7 @@ function db_truncate($table, array $options = array()) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call select() on it. E.g.
+ *   call select() on it. For example,
  *   $injected_database->select($table, $alias, $options);
  *
  * @see \Drupal\Core\Database\Connection::select()
@@ -304,7 +309,7 @@ function db_select($table, $alias = NULL, array $options = array()) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call startTransaction() on it. E.g.
+ *   call startTransaction() on it. For example,
  *   $injected_database->startTransaction($name);
  *
  * @see \Drupal\Core\Database\Connection::startTransaction()
@@ -346,7 +351,8 @@ function db_set_active($key = 'default') {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call escapeTable() on it. E.g. $injected_database->escapeTable($table);
+ *   call escapeTable() on it. For example,
+ *   $injected_database->escapeTable($table);
  *
  * @see \Drupal\Core\Database\Connection::escapeTable()
  */
@@ -367,7 +373,8 @@ function db_escape_table($table) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call escapeTable() on it. E.g. $injected_database->escapeTable($table);
+ *   call escapeTable() on it. For example,
+ *   $injected_database->escapeTable($table);
  *
  * @see \Drupal\Core\Database\Connection::escapeField()
  */
@@ -407,7 +414,8 @@ function db_escape_field($field) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call escapeLike() on it. E.g. $injected_database->escapeLike($string);
+ *   call escapeLike() on it. For example,
+ *   $injected_database->escapeLike($string);
  *
  * @see \Drupal\Core\Database\Connection::escapeLike()
  */
@@ -423,7 +431,7 @@ function db_like($string) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call driver() on it. E.g. $injected_database->driver($string);
+ *   call driver() on it. For example, $injected_database->driver($string);
  *
  * @see \Drupal\Core\Database\Connection::driver()
  */
@@ -467,7 +475,7 @@ function db_close(array $options = array()) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container and
- *   call nextId() on it. E.g. $injected_database->nextId($existing_id);
+ *   call nextId() on it. For example, $injected_database->nextId($existing_id);
  *
  * @see \Drupal\Core\Database\Connection::nextId()
  */
@@ -565,7 +573,7 @@ function db_condition($conjunction) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call createTable() on it. E.g.
+ *   its schema driver, and call createTable() on it. For example,
  *   $injected_database->schema()->createTable($name, $table);
  *
  * @see \Drupal\Core\Database\Schema::createTable()
@@ -588,7 +596,7 @@ function db_create_table($name, $table) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call fieldNames() on it. E.g.
+ *   its schema driver, and call fieldNames() on it. For example,
  *   $injected_database->schema()->fieldNames($fields);
  *
  * @see \Drupal\Core\Database\Schema::fieldNames()
@@ -610,7 +618,7 @@ function db_field_names($fields) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call indexExists() on it. E.g.
+ *   its schema driver, and call indexExists() on it. For example,
  *   $injected_database->schema()->indexExists($table, $name);
  *
  * @see \Drupal\Core\Database\Schema::indexExists()
@@ -630,7 +638,7 @@ function db_index_exists($table, $name) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call tableExists() on it. E.g.
+ *   its schema driver, and call tableExists() on it. For example,
  *   $injected_database->schema()->tableExists($table);
  *
  * @see \Drupal\Core\Database\Schema::tableExists()
@@ -652,7 +660,7 @@ function db_table_exists($table) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call fieldExists() on it. E.g.
+ *   its schema driver, and call fieldExists() on it. For example,
  *   $injected_database->schema()->fieldExists($table, $field);
  *
  * @see \Drupal\Core\Database\Schema::fieldExists()
@@ -672,7 +680,7 @@ function db_field_exists($table, $field) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call findTables() on it. E.g.
+ *   its schema driver, and call findTables() on it. For example,
  *   $injected_database->schema()->findTables($table_expression);
  *
  * @see \Drupal\Core\Database\Schema::findTables()
@@ -691,7 +699,7 @@ function db_find_tables($table_expression) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call renameTable() on it. E.g.
+ *   its schema driver, and call renameTable() on it. For example,
  *   $injected_database->schema()->renameTable($table, $new_name);
  *
  * @see \Drupal\Core\Database\Schema::renameTable()
@@ -708,7 +716,7 @@ function db_rename_table($table, $new_name) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call dropTable() on it. E.g.
+ *   its schema driver, and call dropTable() on it. For example,
  *   $injected_database->schema()->dropTable($table);
  *
  * @see \Drupal\Core\Database\Schema::dropTable()
@@ -738,7 +746,7 @@ function db_drop_table($table) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call addField() on it. E.g.
+ *   its schema driver, and call addField() on it. For example,
  *   $injected_database->schema()->addField($table, $field, $spec, $keys_new);
  *
  * @see \Drupal\Core\Database\Schema::addField()
@@ -762,7 +770,7 @@ function db_add_field($table, $field, $spec, $keys_new = array()) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call dropField() on it. E.g.
+ *   its schema driver, and call dropField() on it. For example,
  *   $injected_database->schema()->dropField($table, $field);
  *
  * @see \Drupal\Core\Database\Schema::dropField()
@@ -783,7 +791,7 @@ function db_drop_field($table, $field) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call fieldSetDefault() on it. E.g.
+ *   its schema driver, and call fieldSetDefault() on it. For example,
  *   $injected_database->schema()->fieldSetDefault($table, $field, $default);
  *
  * @see \Drupal\Core\Database\Schema::fieldSetDefault()
@@ -802,7 +810,7 @@ function db_field_set_default($table, $field, $default) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call fieldSetNoDefault() on it. E.g.
+ *   its schema driver, and call fieldSetNoDefault() on it. For example,
  *   $injected_database->schema()->fieldSetNoDefault($table, $field);
  *
  * @see \Drupal\Core\Database\Schema::fieldSetNoDefault()
@@ -821,7 +829,7 @@ function db_field_set_no_default($table, $field) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call addPrimaryKey() on it. E.g.
+ *   its schema driver, and call addPrimaryKey() on it. For example,
  *   $injected_database->schema()->addPrimaryKey($table, $fields);
  *
  * @see \Drupal\Core\Database\Schema::addPrimaryKey()
@@ -842,7 +850,7 @@ function db_add_primary_key($table, $fields) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call dropPrimaryKey() on it. E.g.
+ *   its schema driver, and call dropPrimaryKey() on it. For example,
  *   $injected_database->schema()->dropPrimaryKey($table);
  *
  * @see \Drupal\Core\Database\Schema::dropPrimaryKey()
@@ -863,7 +871,7 @@ function db_drop_primary_key($table) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call addUniqueKey() on it. E.g.
+ *   its schema driver, and call addUniqueKey() on it. For example,
  *   $injected_database->schema()->addUniqueKey($table, $name, $fields);
  *
  * @see \Drupal\Core\Database\Schema::addUniqueKey()
@@ -886,7 +894,7 @@ function db_add_unique_key($table, $name, $fields) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call dropUniqueKey() on it. E.g.
+ *   its schema driver, and call dropUniqueKey() on it. For example,
  *   $injected_database->schema()->dropUniqueKey($table, $name);
  *
  * @see \Drupal\Core\Database\Schema::dropUniqueKey()
@@ -911,7 +919,7 @@ function db_drop_unique_key($table, $name) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call addIndex() on it. E.g.
+ *   its schema driver, and call addIndex() on it. For example,
  *   $injected_database->schema()->addIndex($table, $name, $fields, $spec);
  *
  * @see hook_schema()
@@ -936,7 +944,7 @@ function db_add_index($table, $name, $fields, array $spec) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call dropIndex() on it. E.g.
+ *   its schema driver, and call dropIndex() on it. For example,
  *   $injected_database->schema()->dropIndex($table, $name);
  *
  * @see \Drupal\Core\Database\Schema::dropIndex()
@@ -1007,7 +1015,7 @@ function db_drop_index($table, $name) {
  *
  * @deprecated as of Drupal 8.0.x, will be removed in Drupal 9.0.0. Instead, get
  *   a database connection injected into your service from the container, get
- *   its schema driver, and call changeField() on it. E.g.
+ *   its schema driver, and call changeField() on it. For example,
  *   $injected_database->schema()->changeField($table, $field, $field_new, $spec, $keys_new);
  *
  * @see \Drupal\Core\Database\Schema::changeField()

core/includes/theme.inc

@@ -727,7 +727,8 @@ function template_preprocess_links(&$variables) {
  *     to an empty string, but can be set to NULL for the attribute to be
  *     omitted. Usually, neither omission nor an empty string satisfies
  *     accessibility requirements, so it is strongly encouraged for code
- *     calling _theme('image') to pass a meaningful value for this variable.
+ *     building variables for image.html.twig templates to pass a meaningful
+ *     value for this variable.
  *     - http://www.w3.org/TR/REC-html40/struct/objects.html#h-13.8
  *     - http://www.w3.org/TR/xhtml1/dtds.html
  *     - http://dev.w3.org/html5/spec/Overview.html#alt
@@ -1519,7 +1520,7 @@ function template_preprocess_field(&$variables, $hook) {
   }
 
   // Merge attributes when a single-value field has a hidden label.
-  if ($element['#label_display'] == 'hidden' && !$variables['multiple']) {
+  if ($element['#label_display'] == 'hidden' && !$variables['multiple'] && !empty($element['#items'][0]->_attributes)) {
     $variables['attributes'] = NestedArray::mergeDeep($variables['attributes'], (array) $element['#items'][0]->_attributes);
   }
 
@@ -1721,11 +1722,12 @@ function drupal_common_theme() {
     'image' => array(
       // HTML 4 and XHTML 1.0 always require an alt attribute. The HTML 5 draft
       // allows the alt attribute to be omitted in some cases. Therefore,
-      // default the alt attribute to an empty string, but allow code calling
+      // default the alt attribute to an empty string, but allow code providing
-      // _theme('image') to pass explicit NULL for it to be omitted. Usually,
+      // variables to image.html.twig templates to pass explicit NULL for it to
-      // neither omission nor an empty string satisfies accessibility
+      // be omitted. Usually, neither omission nor an empty string satisfies
-      // requirements, so it is strongly encouraged for code calling
+      // accessibility requirements, so it is strongly encouraged for code
-      // _theme('image') to pass a meaningful value for the alt variable.
+      // building variables for image.html.twig templates to pass a meaningful
+      // value for the alt variable.
       // - http://www.w3.org/TR/REC-html40/struct/objects.html#h-13.8
       // - http://www.w3.org/TR/xhtml1/dtds.html
       // - http://dev.w3.org/html5/spec/Overview.html#alt
@@ -1765,7 +1767,7 @@ function drupal_common_theme() {
       'render element' => 'page',
     ),
     'maintenance_task_list' => array(
-      'variables' => array('items' => NULL, 'active' => NULL,  'variant' => NULL),
+      'variables' => array('items' => NULL, 'active' => NULL, 'variant' => NULL),
     ),
     'authorize_report' => array(
       'variables' => ['messages' => [], 'attributes' => []],

core/install.php

@@ -26,6 +26,11 @@ if (version_compare(PHP_VERSION, '5.5.9') < 0) {
   exit;
 }
 
+if (function_exists('opcache_get_status') && opcache_get_status()['opcache_enabled'] && !ini_get('opcache.save_comments')) {
+  print 'Systems with OPcache installed must have <a href="http://php.net/manual/en/opcache.configuration.php#ini.opcache.save-comments">opcache.save_comments</a> enabled.';
+  exit();
+}
+
 // Start the installer.
 $class_loader = require_once 'autoload.php';
 require_once __DIR__ . '/includes/install.core.inc';

core/lib/Drupal.php

@@ -63,8 +63,8 @@ use Drupal\Core\Url;
  *   class StuffDoingClass implements StuffDoingInterface {
  *     protected $lockBackend;
  *
- *     public function __construct(LockBackendInterface $lockBackend) {
+ *     public function __construct(LockBackendInterface $lock_backend) {
- *       $this->lockBackend = $lockBackend;
+ *       $this->lockBackend = $lock_backend;
  *     }
  *
  *     public function doStuff() {
@@ -81,7 +81,7 @@ class Drupal {
   /**
    * The current system version.
    */
-  const VERSION = '8.0.1';
+  const VERSION = '8.0.2';
 
   /**
    * Core API compatibility.
@@ -423,11 +423,11 @@ class Drupal {
    * Returns the entity query object for this entity type.
    *
    * @param string $entity_type
-   *   The entity type, e.g. node, for which the query object should be
+   *   The entity type (for example, node) for which the query object should be
    *   returned.
    * @param string $conjunction
-   *   AND if all conditions in the query need to apply, OR if any of them is
+   *   (optional) Either 'AND' if all conditions in the query need to apply, or
-   *   enough. Optional, defaults to AND.
+   *   'OR' if any of them is sufficient. Defaults to 'AND'.
    *
    * @return \Drupal\Core\Entity\Query\QueryInterface
    *   The query object that can query the given entity type.
@@ -440,11 +440,11 @@ class Drupal {
    * Returns the entity query aggregate object for this entity type.
    *
    * @param string $entity_type
-   *   The entity type, e.g. node, for which the query object should be
+   *   The entity type (for example, node) for which the query object should be
    *   returned.
    * @param string $conjunction
-   *   AND if all conditions in the query need to apply, OR if any of them is
+   *   (optional) Either 'AND' if all conditions in the query need to apply, or
-   *   enough. Optional, defaults to AND.
+   *   'OR' if any of them is sufficient. Defaults to 'AND'.
    *
    * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
    *   The query object that can query the given entity type.

core/lib/Drupal/Component/FileCache/ApcuFileCacheBackend.php

@@ -16,21 +16,21 @@ class ApcuFileCacheBackend implements FileCacheBackendInterface {
    * {@inheritdoc}
    */
   public function fetch(array $cids) {
-    return apc_fetch($cids);
+    return apcu_fetch($cids);
   }
 
   /**
    * {@inheritdoc}
    */
   public function store($cid, $data) {
-    apc_store($cid, $data);
+    apcu_store($cid, $data);
   }
 
   /**
    * {@inheritdoc}
    */
   public function delete($cid) {
-    apc_delete($cid);
+    apcu_delete($cid);
   }
 
 }

core/lib/Drupal/Component/Gettext/PoHeader.php

@@ -471,10 +471,10 @@ class PoHeader {
    *
    * @param array $element_stack
    *   Array of plural formula values and operators create by parseArithmetic().
-   * @param integer $n
+   * @param int $n
    *   The @count number for which we are determining the right plural position.
    *
-   * @return integer
+   * @return int
    *   Number of the plural string to be used for the given plural value.
    *
    * @see parseArithmetic()

core/lib/Drupal/Component/Utility/Number.php

@@ -21,11 +21,11 @@ class Number {
    *
    * This is based on the number/range verification methods of webkit.
    *
-   * @param numeric $value
+   * @param float $value
    *   The value that needs to be checked.
-   * @param numeric $step
+   * @param float $step
    *   The step scale factor. Must be positive.
-   * @param numeric $offset
+   * @param float $offset
    *   (optional) An offset, to which the difference must be a multiple of the
    *   given step.
    *

core/lib/Drupal/Component/Utility/OpCodeCache.php

@@ -30,16 +30,6 @@ class OpCodeCache {
     if (function_exists('opcache_invalidate')) {
       opcache_invalidate($pathname, TRUE);
     }
-    // If apcu extension is enabled in PHP 5.5 or greater it emulates apc.
-    // This is to provide an easy upgrade path if you are using apc's user
-    // caching however the emulation does not extend to opcode caching.
-    // Therefore we need to check if the function exists as well.
-    if (extension_loaded('apc') && function_exists('apc_delete_file')) {
-      // apc_delete_file() throws a PHP warning in case the specified file was
-      // not compiled yet.
-      // @see http://php.net/manual/en/function.apc-delete-file.php
-      @apc_delete_file($pathname);
-    }
   }
 
 }

core/lib/Drupal/Component/Utility/UrlHelper.php

@@ -36,10 +36,11 @@ class UrlHelper {
    *   http_build_query() directly.
    *
    * @param array $query
-   *   The query parameter array to be processed,
+   *   The query parameter array to be processed; for instance,
-   *   e.g. \Drupal::request()->query->all().
+   *   \Drupal::request()->query->all().
    * @param string $parent
-   *   Internal use only. Used to build the $query array key for nested items.
+   *   (optional) Internal use only. Used to build the $query array key for
+   *   nested items. Defaults to an empty string.
    *
    * @return string
    *   A rawurlencoded string which can be used as or appended to the URL query
@@ -168,8 +169,8 @@ class UrlHelper {
     }
     // Internal URLs.
     else {
-      // parse_url() does not support relative URLs, so make it absolute. E.g. the
+      // parse_url() does not support relative URLs, so make it absolute. For
-      // relative URL "foo/bar:1" isn't properly parsed.
+      // instance, the relative URL "foo/bar:1" isn't properly parsed.
       $parts = parse_url('http://example.com/' . $url);
       // Strip the leading slash that was just added.
       $options['path'] = substr($parts['path'], 1);
@@ -200,10 +201,11 @@ class UrlHelper {
   }
 
   /**
-   * Determines whether a path is external to Drupal (e.g. http://example.com).
+   * Determines whether a path is external to Drupal.
    *
-   * If a path cannot be assessed by Drupal's menu handler, then we must
+   * An example of an external path is http://example.com. If a path cannot be
-   * treat it as potentially insecure.
+   * assessed by Drupal's menu handler, then we must treat it as potentially
+   * insecure.
    *
    * @param string $path
    *   The internal path or external URL being linked to, such as "node/34" or
@@ -296,7 +298,7 @@ class UrlHelper {
   }
 
   /**
-   * Strips dangerous protocols (e.g. 'javascript:') from a URI.
+   * Strips dangerous protocols (for example, 'javascript:') from a URI.
    *
    * This function must be called for all URIs within user-entered input prior
    * to being output to an HTML attribute value. It is often called as part of
@@ -316,8 +318,8 @@ class UrlHelper {
    *   for well-formed URLs will be invoked, which strips most substrings that
    *   precede a ":". The result can be used in URL attributes such as "href"
    *   or "src" (only after calling Html::escape() separately), but this may not
-   *   produce valid HTML (e.g., malformed URLs within "href" attributes fail
+   *   produce valid HTML (for example, malformed URLs within "href" attributes
-   *   HTML validation). This can be avoided by using
+   *   fail HTML validation). This can be avoided by using
    *   Url::fromUri($possibly_not_a_url)->toString(), which either throws an
    *   exception or returns a well-formed URL.
    *

core/lib/Drupal/Core/Access/CustomAccessCheck.php

@@ -55,6 +55,8 @@ class CustomAccessCheck implements RoutingAccessInterface {
   /**
    * Checks access for the account and route using the custom access checker.
    *
+   * @param \Symfony\Component\Routing\Route $route
+   *   The route.
    * @param \Drupal\Core\Routing\RouteMatchInterface $route_match
    *   The route match object to be checked.
    * @param \Drupal\Core\Session\AccountInterface $account

core/lib/Drupal/Core/Annotation/QueueWorker.php

@@ -10,18 +10,21 @@ namespace Drupal\Core\Annotation;
 use Drupal\Component\Annotation\Plugin;
 
 /**
- * Declare queue workers that need to be run periodically.
+ * Declare a worker class for processing a queue item.
  *
- * While there can be only one hook_cron() process running at the same time,
+ * Worker plugins are used by some queues for processing the individual items
- * there can be any number of processes defined here running. Because of
+ * in the queue. In that case, the ID of the worker plugin needs to match the
- * this, long running tasks are much better suited for this API. Items queued
+ * machine name of a queue, so that you can retrieve the queue back end by
- * in hook_cron() might be processed in the same cron run if there are not many
+ * calling \Drupal\Core\Queue\QueueFactory::get($plugin_id).
- * items in the queue, otherwise it might take several requests, which can be
- * run in parallel.
  *
- * You can create queues, add items to them, claim them, etc. without using a
+ * \Drupal\Core\Cron::processQueues() processes queues that use workers; they
- * QueueWorker plugin if you want, however, you need to take care of processing
+ * can also be processed outside of the cron process.
- * the items in the queue in that case. See \Drupal\Core\Cron for an example.
+ *
+ * Some queues do not use worker plugins: you can create queues, add items to
+ * them, claim them, etc. without using a QueueWorker plugin. However, you will
+ * need to take care of processing the items in the queue in that case. You can
+ * look at \Drupal\Core\Cron::processQueues() for an example of how to process
+ * a queue that uses workers, and adapt it to your queue.
  *
  * Plugin Namespace: Plugin\QueueWorker
  *

core/lib/Drupal/Core/Asset/LibraryDiscoveryCollector.php

@@ -51,14 +51,14 @@ class LibraryDiscoveryCollector extends CacheCollector {
   /**
    * Constructs a CacheCollector object.
    *
-   * @param string $cid
-   *   The cid for the array being cached.
    * @param \Drupal\Core\Cache\CacheBackendInterface $cache
    *   The cache backend.
    * @param \Drupal\Core\Lock\LockBackendInterface $lock
    *   The lock backend.
    * @param \Drupal\Core\Asset\LibraryDiscoveryParser $discovery_parser
    *   The library discovery parser.
+   * @param \Drupal\Core\Theme\ThemeManagerInterface $theme_manager
+   *   The theme manager.
    */
   public function __construct(CacheBackendInterface $cache, LockBackendInterface $lock, LibraryDiscoveryParser $discovery_parser, ThemeManagerInterface $theme_manager) {
     $this->themeManager = $theme_manager;

core/lib/Drupal/Core/Asset/LibraryDiscoveryParser.php

@@ -50,6 +50,8 @@ class LibraryDiscoveryParser {
    *   The app root.
    * @param \Drupal\Core\Extension\ModuleHandlerInterface $module_handler
    *   The module handler.
+   * @param \Drupal\Core\Theme\ThemeManagerInterface $theme_manager
+   *   The theme manager.
    */
   public function __construct($root, ModuleHandlerInterface $module_handler, ThemeManagerInterface $theme_manager) {
     $this->root = $root;

core/lib/Drupal/Core/Authentication/AuthenticationProviderFilterInterface.php

@@ -13,8 +13,9 @@ use Symfony\Component\HttpFoundation\Request;
  * Restrict authentication methods to a subset of the site.
  *
  * Some authentication methods should not be available throughout a whole site.
- * E.g., there are good reasons to restrict insecure methods like HTTP basic
+ * For instance, there are good reasons to restrict insecure methods like HTTP
- * auth or an URL token authentication method to API-only routes.
+ * basic authentication or an URL token authentication method to API-only
+ * routes.
  */
 interface AuthenticationProviderFilterInterface {
 

core/lib/Drupal/Core/Cache/Apcu4Backend.php

@@ -0,0 +1,26 @@
+<?php
+
+/**
+ * @file
+ * Contains \Drupal\Core\Cache\Apcu4Backend.
+ */
+
+namespace Drupal\Core\Cache;
+
+/**
+ * Stores cache items in the Alternative PHP Cache User Cache (APCu).
+ *
+ * This class is used with APCu versions >= 4.0.0 and < 5.0.0.
+ */
+class Apcu4Backend extends ApcuBackend {
+
+  /**
+   * {@inheritdoc}
+   *
+   * @return \APCIterator
+   */
+  protected function getIterator($search = NULL, $format = APC_ITER_ALL, $chunk_size = 100, $list = APC_LIST_ACTIVE) {
+    return new \APCIterator('user', $search, $format, $chunk_size, $list);
+  }
+
+}

core/lib/Drupal/Core/Cache/ApcuBackend.php

@@ -60,7 +60,7 @@ class ApcuBackend implements CacheBackendInterface {
   }
 
   /**
-   * Prepends the APC user variable prefix for this bin to a cache item ID.
+   * Prepends the APCu user variable prefix for this bin to a cache item ID.
    *
    * @param string $cid
    *   The cache item ID to prefix.
@@ -76,7 +76,7 @@ class ApcuBackend implements CacheBackendInterface {
    * {@inheritdoc}
    */
   public function get($cid, $allow_invalid = FALSE) {
-    $cache = apc_fetch($this->getApcuKey($cid));
+    $cache = apcu_fetch($this->getApcuKey($cid));
     return $this->prepareItem($cache, $allow_invalid);
   }
 
@@ -90,7 +90,7 @@ class ApcuBackend implements CacheBackendInterface {
       $map[$this->getApcuKey($cid)] = $cid;
     }
 
-    $result = apc_fetch(array_keys($map));
+    $result = apcu_fetch(array_keys($map));
     $cache = array();
     if ($result) {
       foreach ($result as $key => $item) {
@@ -112,18 +112,18 @@ class ApcuBackend implements CacheBackendInterface {
    * APCu is a memory cache, shared across all server processes. To prevent
    * cache item clashes with other applications/installations, every cache item
    * is prefixed with a unique string for this site. Therefore, functions like
-   * apc_clear_cache() cannot be used, and instead, a list of all cache items
+   * apcu_clear_cache() cannot be used, and instead, a list of all cache items
    * belonging to this application need to be retrieved through this method
    * instead.
    *
    * @param string $prefix
    *   (optional) A cache ID prefix to limit the result to.
    *
-   * @return \APCIterator
+   * @return \APCUIterator
-   *   An APCIterator containing matched items.
+   *   An APCUIterator containing matched items.
    */
   protected function getAll($prefix = '') {
-    return new \APCIterator('user', '/^' . preg_quote($this->getApcuKey($prefix), '/') . '/');
+    return $this->getIterator('/^' . preg_quote($this->getApcuKey($prefix), '/') . '/');
   }
 
   /**
@@ -174,12 +174,12 @@ class ApcuBackend implements CacheBackendInterface {
     $cache->expire = $expire;
     $cache->tags = implode(' ', $tags);
     $cache->checksum = $this->checksumProvider->getCurrentChecksum($tags);
-    // APC serializes/unserializes any structure itself.
+    // APCu serializes/unserializes any structure itself.
     $cache->serialized = 0;
     $cache->data = $data;
 
     // Expiration is handled by our own prepareItem(), not APCu.
-    apc_store($this->getApcuKey($cid), $cache);
+    apcu_store($this->getApcuKey($cid), $cache);
   }
 
   /**
@@ -195,35 +195,35 @@ class ApcuBackend implements CacheBackendInterface {
    * {@inheritdoc}
    */
   public function delete($cid) {
-    apc_delete($this->getApcuKey($cid));
+    apcu_delete($this->getApcuKey($cid));
   }
 
   /**
    * {@inheritdoc}
    */
   public function deleteMultiple(array $cids) {
-    apc_delete(array_map(array($this, 'getApcuKey'), $cids));
+    apcu_delete(array_map(array($this, 'getApcuKey'), $cids));
   }
 
   /**
    * {@inheritdoc}
    */
   public function deleteAll() {
-    apc_delete(new \APCIterator('user', '/^' . preg_quote($this->binPrefix, '/') . '/'));
+    apcu_delete($this->getIterator('/^' . preg_quote($this->binPrefix, '/') . '/'));
   }
 
   /**
    * {@inheritdoc}
    */
   public function garbageCollection() {
-    // APC performs garbage collection automatically.
+    // APCu performs garbage collection automatically.
   }
 
   /**
    * {@inheritdoc}
    */
   public function removeBin() {
-    apc_delete(new \APCIterator('user', '/^' . preg_quote($this->binPrefix, '/') . '/'));
+    apcu_delete($this->getIterator('/^' . preg_quote($this->binPrefix, '/') . '/'));
   }
 
   /**
@@ -252,4 +252,25 @@ class ApcuBackend implements CacheBackendInterface {
     }
   }
 
+  /**
+   * Instantiates and returns the APCUIterator class.
+   *
+   * @param mixed $search
+   *   A PCRE regular expression that matches against APC key names, either as a
+   *   string for a single regular expression, or as an array of regular
+   *   expressions. Or, optionally pass in NULL to skip the search.
+   * @param int $format
+   *   The desired format, as configured with one or more of the APC_ITER_*
+   *   constants.
+   * @param int $chunk_size
+   *   The chunk size. Must be a value greater than 0. The default value is 100.
+   * @param int $list
+   *   The type to list. Either pass in APC_LIST_ACTIVE or APC_LIST_DELETED.
+   *
+   * @return \APCUIterator
+   */
+  protected function getIterator($search = NULL, $format = APC_ITER_ALL, $chunk_size = 100, $list = APC_LIST_ACTIVE) {
+    return new \APCUIterator($search, $format, $chunk_size, $list);
+  }
+
 }

core/lib/Drupal/Core/Cache/ApcuBackendFactory.php

@@ -25,6 +25,13 @@ class ApcuBackendFactory implements CacheFactoryInterface {
    */
   protected $checksumProvider;
 
+  /**
+   * The APCU backend class to use.
+   *
+   * @var string
+   */
+  protected $backendClass;
+
   /**
    * Constructs an ApcuBackendFactory object.
    *
@@ -38,6 +45,12 @@ class ApcuBackendFactory implements CacheFactoryInterface {
   public function __construct($root, $site_path, CacheTagsChecksumInterface $checksum_provider) {
     $this->sitePrefix = Settings::getApcuPrefix('apcu_backend', $root, $site_path);
     $this->checksumProvider = $checksum_provider;
+    if (version_compare(phpversion('apcu'), '5.0.0', '>=')) {
+      $this->backendClass = 'Drupal\Core\Cache\ApcuBackend';
+    }
+    else {
+      $this->backendClass = 'Drupal\Core\Cache\Apcu4Backend';
+    }
   }
 
   /**
@@ -50,7 +63,7 @@ class ApcuBackendFactory implements CacheFactoryInterface {
    *   The cache backend object for the specified cache bin.
    */
   public function get($bin) {
-    return new ApcuBackend($bin, $this->sitePrefix, $this->checksumProvider);
+    return new $this->backendClass($bin, $this->sitePrefix, $this->checksumProvider);
   }
 
 }

core/lib/Drupal/Core/Cache/CacheFactory.php

@@ -14,7 +14,7 @@ use Drupal\Core\Site\Settings;
 use Symfony\Component\DependencyInjection\ContainerAwareInterface;
 use Symfony\Component\DependencyInjection\ContainerAwareTrait;
 
-class CacheFactory implements CacheFactoryInterface,  ContainerAwareInterface {
+class CacheFactory implements CacheFactoryInterface, ContainerAwareInterface {
 
   use ContainerAwareTrait;
 

core/lib/Drupal/Core/Cache/CacheableResponseInterface.php

@@ -17,9 +17,9 @@ interface CacheableResponseInterface {
   /**
    * Adds a dependency on an object: merges its cacheability metadata.
    *
-   * E.g. when a response depends on some configuration, an entity, or an access
+   * For instance, when a response depends on some configuration, an entity, or
-   * result, we must make sure their cacheability metadata is present on the
+   * an access result, we must make sure their cacheability metadata is present
-   * response. This method makes doing that simple.
+   * on the response. This method makes doing that simple.
    *
    * @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $dependency
    *   The dependency. If the object implements CacheableDependencyInterface,

core/lib/Drupal/Core/Cache/ChainedFastBackendFactory.php

@@ -53,7 +53,7 @@ class ChainedFastBackendFactory implements CacheFactoryInterface {
     }
 
     // Default the fast backend to APCu if it's available.
-    if (!isset($fast_service_name) && function_exists('apc_fetch')) {
+    if (!isset($fast_service_name) && function_exists('apcu_fetch')) {
       $fast_service_name = 'cache.backend.apcu';
     }
 

core/lib/Drupal/Core/Cache/Context/CacheContextsManager.php

@@ -92,9 +92,10 @@ class CacheContextsManager {
    *
    * A cache context token is either:
    * - a cache context ID (if the service ID is 'cache_context.foo', then 'foo'
-   *   is a cache context ID), e.g. 'foo'
+   *   is a cache context ID); for example, 'foo'.
-   * - a calculated cache context ID, followed by a double colon, followed by
+   * - a calculated cache context ID, followed by a colon, followed by
-   *   the parameter for the calculated cache context, e.g. 'bar:some_parameter'
+   *   the parameter for the calculated cache context; for example,
+   *   'bar:some_parameter'.
    *
    * @param string[] $context_tokens
    *   An array of cache context tokens.
@@ -142,11 +143,12 @@ class CacheContextsManager {
    * If a cache context is being optimized away, it is able to set cacheable
    * metadata for itself which will be bubbled up.
    *
-   * E.g. when caching per user ('user'), also caching per role ('user.roles')
+   * For example, when caching per user ('user'), also caching per role
-   * is meaningless because "per role" is implied by "per user".
+   * ('user.roles') is meaningless because "per role" is implied by "per user".
    *
-   * Examples — remember that the period indicates hierarchy and the colon can
+   * In the following examples, remember that the period indicates hierarchy and
-   * be used to get a specific value of a calculated cache context:
+   * the colon can be used to get a specific value of a calculated cache
+   * context:
    * - ['a', 'a.b'] -> ['a']
    * - ['a', 'a.b.c'] -> ['a']
    * - ['a.b', 'a.b.c'] -> ['a.b']

core/lib/Drupal/Core/Condition/ConditionManager.php

@@ -49,7 +49,7 @@ class ConditionManager extends DefaultPluginManager implements ExecutableManager
   }
 
   /**
-   * Override of Drupal\Component\Plugin\PluginManagerBase::createInstance().
+   * {@inheritdoc}
    */
   public function createInstance($plugin_id, array $configuration = array()) {
     $plugin = $this->getFactory()->createInstance($plugin_id, $configuration);

core/lib/Drupal/Core/Config/ConfigInstaller.php

@@ -7,6 +7,7 @@
 
 namespace Drupal\Core\Config;
 
+use Drupal\Component\Utility\Crypt;
 use Drupal\Component\Utility\Unicode;
 use Drupal\Core\Config\Entity\ConfigDependencyManager;
 use Drupal\Core\Config\Entity\ConfigEntityDependency;
@@ -279,6 +280,12 @@ class ConfigInstaller implements ConfigInstallerInterface {
       }
       if ($config_to_create[$name] !== FALSE) {
         $new_config->setData($config_to_create[$name]);
+        // Add a hash to configuration created through the installer so it is
+        // possible to know if the configuration was created by installing an
+        // extension and to track which version of the default config was used.
+        if (!$this->isSyncing() && $collection == StorageInterface::DEFAULT_COLLECTION) {
+          $new_config->set('_core.default_config_hash', Crypt::hashBase64(serialize($config_to_create[$name])));
+        }
       }
       if ($collection == StorageInterface::DEFAULT_COLLECTION && $entity_type = $this->configManager->getEntityTypeIdByName($name)) {
         // If we are syncing do not create configuration entities. Pluggable

core/lib/Drupal/Core/Config/Entity/ConfigEntityBase.php

@@ -103,6 +103,17 @@ abstract class ConfigEntityBase extends Entity implements ConfigEntityInterface
    */
   protected $third_party_settings = array();
 
+  /**
+   * Information maintained by Drupal core about configuration.
+   *
+   * Keys:
+   * - default_config_hash: A hash calculated by the config.installer service
+   *   and added during installation.
+   *
+   * @var array
+   */
+  protected $_core = [];
+
   /**
    * Trust supplied data and not use configuration schema on save.
    *
@@ -296,6 +307,9 @@ abstract class ConfigEntityBase extends Entity implements ConfigEntityInterface
     if (empty($this->third_party_settings)) {
       unset($properties['third_party_settings']);
     }
+    if (empty($this->_core)) {
+      unset($properties['_core']);
+    }
     return $properties;
   }
 

core/lib/Drupal/Core/Config/Entity/ConfigEntityBundleBase.php

@@ -54,6 +54,7 @@ abstract class ConfigEntityBundleBase extends ConfigEntityBase {
       }
       // Entity bundle field definitions may depend on bundle settings.
       $entity_manager->clearCachedFieldDefinitions();
+      $entity_manager->clearCachedBundles();
     }
   }
 

core/lib/Drupal/Core/Config/Entity/ConfigEntityStorageInterface.php

@@ -18,10 +18,10 @@ interface ConfigEntityStorageInterface extends EntityStorageInterface {
    * Extracts the configuration entity ID from the full configuration name.
    *
    * @param string $config_name
-   *   The full configuration name to extract the ID from. E.g.
+   *   The full configuration name to extract the ID from; for example,
    *   'views.view.archive'.
    * @param string $config_prefix
-   *   The config prefix of the configuration entity. E.g. 'views.view'
+   *   The config prefix of the configuration entity; for example, 'views.view'.
    *
    * @return string
    *   The ID of the configuration entity.

core/lib/Drupal/Core/Config/Entity/ConfigEntityType.php

@@ -157,6 +157,7 @@ class ConfigEntityType extends EntityType implements ConfigEntityTypeInterface {
           'status' => 'status',
           'dependencies' => 'dependencies',
           'third_party_settings' => 'third_party_settings',
+          '_core' => '_core',
         ];
         foreach ($this->config_export as $property => $name) {
           if (is_numeric($property)) {

core/lib/Drupal/Core/Config/InstallStorage.php

@@ -80,9 +80,9 @@ class InstallStorage extends FileStorage {
    *   The path to the configuration file.
    *
    * @todo Improve this when figuring out how we want to handle configuration in
-   *   installation profiles. E.g., a config object actually has to be searched
+   *   installation profiles. For instance, a config object actually has to be
-   *   in the profile first (whereas the profile is never the owner), only
+   *   searched in the profile first (whereas the profile is never the owner);
-   *   afterwards check for a corresponding module or theme.
+   *   only afterwards check for a corresponding module or theme.
    */
   public function getFilePath($name) {
     $folders = $this->getAllFolders();

core/lib/Drupal/Core/CoreServiceProvider.php

@@ -105,8 +105,8 @@ class CoreServiceProvider implements ServiceProviderInterface  {
   /**
    * Determines and registers the UUID service.
    *
-   * @param \Symfony\Component\DependencyInjection\ContainerBuilder $container
+   * @param \Drupal\Core\DependencyInjection\ContainerBuilder $container
-   *   The container.
+   *   The container builder.
    *
    * @return string
    *   Class name for the UUID service.
@@ -131,6 +131,9 @@ class CoreServiceProvider implements ServiceProviderInterface  {
 
   /**
    * Registers services and event subscribers for a site under test.
+   *
+   * @param \Drupal\Core\DependencyInjection\ContainerBuilder $container
+   *   The container builder.
    */
   protected function registerTest(ContainerBuilder $container) {
     // Do nothing if we are not in a test environment.

core/lib/Drupal/Core/Database/Connection.php

@@ -90,7 +90,7 @@ abstract class Connection {
   /**
    * An index used to generate unique temporary table names.
    *
-   * @var integer
+   * @var int
    */
   protected $temporaryNameIndex = 0;
 

core/lib/Drupal/Core/Database/Driver/pgsql/Schema.php

@@ -39,7 +39,7 @@ class Schema extends DatabaseSchema {
    * Value will usually be set to a 63 chars limit but PostgreSQL allows
    * to higher this value before compiling, so we need to check for that.
    *
-   * @var integer
+   * @var int
    */
   protected $maxIdentifierLength;
 

core/lib/Drupal/Core/DrupalKernel.php

@@ -428,7 +428,7 @@ class DrupalKernel implements DrupalKernelInterface, TerminableInterface {
       ];
       // @todo Use extension_loaded('apcu') for non-testbot
       //  https://www.drupal.org/node/2447753.
-      if (function_exists('apc_fetch')) {
+      if (function_exists('apcu_fetch')) {
         $configuration['default']['cache_backend_class'] = '\Drupal\Component\FileCache\ApcuFileCacheBackend';
       }
     }
@@ -968,11 +968,11 @@ class DrupalKernel implements DrupalKernelInterface, TerminableInterface {
       }
     }
 
-    // If the class loader is still the same, possibly upgrade to the APC class
+    // If the class loader is still the same, possibly upgrade to the APCu class
     // loader.
     if ($class_loader_class == get_class($this->classLoader)
         && Settings::get('class_loader_auto_detect', TRUE)
-        && function_exists('apc_fetch')) {
+        && function_exists('apcu_fetch')) {
       $prefix = Settings::getApcuPrefix('class_loader', $this->root);
       $apc_loader = new \Symfony\Component\ClassLoader\ApcClassLoader($prefix, $this->classLoader);
       $this->classLoader->unregister();
@@ -1307,7 +1307,7 @@ class DrupalKernel implements DrupalKernelInterface, TerminableInterface {
    *
    * @return array
    *   Array where each key is a module name, and each value is a path to the
-   *   respective *.module or *.profile file.
+   *   respective *.info.yml file.
    */
   protected function getModuleFileNames() {
     $filenames = array();
@@ -1324,7 +1324,7 @@ class DrupalKernel implements DrupalKernelInterface, TerminableInterface {
    *
    * @param string[] $module_file_names
    *   Array where each key is a module name, and each value is a path to the
-   *   respective *.module or *.profile file.
+   *   respective *.info.yml file.
    *
    * @return string[]
    *   Array where each key is a module namespace like 'Drupal\system', and each

core/lib/Drupal/Core/Entity/Annotation/ConfigEntityType.php

@@ -6,15 +6,14 @@
  */
 
 namespace Drupal\Core\Entity\Annotation;
+
 use Drupal\Core\StringTranslation\TranslatableMarkup;
 
 /**
  * Defines a config entity type annotation object.
  *
- * Config Entity type plugins use an object-based annotation method, rather than an
- * array-type annotation method (as commonly used on other annotation types).
  * The annotation properties of entity types are found on
- * \Drupal\Core\Entity\ConfigEntityType and are accessed using
+ * \Drupal\Core\Config\Entity\ConfigEntityType and are accessed using
  * get/set methods defined in \Drupal\Core\Entity\EntityTypeInterface.
  *
  * @ingroup entity_api

core/lib/Drupal/Core/Entity/Element/EntityAutocomplete.php

@@ -10,6 +10,7 @@ namespace Drupal\Core\Entity\Element;
 use Drupal\Component\Utility\Crypt;
 use Drupal\Component\Utility\Tags;
 use Drupal\Core\Entity\EntityInterface;
+use Drupal\Core\Entity\EntityReferenceSelection\SelectionInterface;
 use Drupal\Core\Entity\EntityReferenceSelection\SelectionWithAutocreateInterface;
 use Drupal\Core\Form\FormStateInterface;
 use Drupal\Core\Render\Element\Textfield;
@@ -146,6 +147,7 @@ class EntityAutocomplete extends Textfield {
         'handler' => $element['#selection_handler'],
         'handler_settings' => $element['#selection_settings'],
       );
+      /** @var /Drupal\Core\Entity\EntityReferenceSelection\SelectionInterface $handler */
       $handler = \Drupal::service('plugin.manager.entity_reference_selection')->getInstance($options);
       $autocreate = (bool) $element['#autocreate'] && $handler instanceof SelectionWithAutocreateInterface;
 
@@ -164,6 +166,7 @@ class EntityAutocomplete extends Textfield {
           );
         }
         elseif ($autocreate) {
+          /** @var \Drupal\Core\Entity\EntityReferenceSelection\SelectionWithAutocreateInterface $handler */
           // Auto-create item. See an example of how this is handled in
           // \Drupal\Core\Field\Plugin\Field\FieldType\EntityReferenceItem::presave().
           $value[] = array(
@@ -211,6 +214,7 @@ class EntityAutocomplete extends Textfield {
           }
 
           foreach ($invalid_new_entities as $entity) {
+            /** @var \Drupal\Core\Entity\EntityInterface $entity */
             $form_state->setError($element, t('This entity (%type: %label) cannot be referenced.', array('%type' => $element['#target_type'], '%label' => $entity->label())));
           }
         }
@@ -233,6 +237,8 @@ class EntityAutocomplete extends Textfield {
    * The method will return an entity ID if one single entity unambuguously
    * matches the incoming input, and sill assign form errors otherwise.
    *
+   * @param \Drupal\Core\Entity\EntityReferenceSelection\SelectionInterface $handler
+   *   Entity reference selection plugin.
    * @param string $input
    *   Single string from autocomplete element.
    * @param array $element
@@ -243,10 +249,10 @@ class EntityAutocomplete extends Textfield {
    *   Whether to trigger a form error if an element from $input (eg. an entity)
    *   is not found.
    *
-   * @return integer|null
+   * @return int|null
    *   Value of a matching entity ID, or NULL if none.
    */
-  protected static function matchEntityByTitle($handler, $input, &$element, FormStateInterface $form_state, $strict) {
+  protected static function matchEntityByTitle(SelectionInterface $handler, $input, array &$element, FormStateInterface $form_state, $strict) {
     $entities_by_bundle = $handler->getReferenceableEntities($input, '=', 6);
     $entities = array_reduce($entities_by_bundle, function ($flattened, $bundle_entities) {
       return $flattened + $bundle_entities;

core/lib/Drupal/Core/Entity/Entity.php

@@ -320,11 +320,6 @@ abstract class Entity implements EntityInterface {
 
   /**
    * {@inheritdoc}
-   *
-   * Returns a list of URI relationships supported by this entity.
-   *
-   * @return array
-   *   An array of link relationships supported by this entity.
    */
   public function uriRelationships() {
     return array_keys($this->linkTemplates());
@@ -497,9 +492,6 @@ abstract class Entity implements EntityInterface {
 
   /**
    * {@inheritdoc}
-   *
-   * @return static|null
-   *   The entity object or NULL if there is no entity with the given ID.
    */
   public static function load($id) {
     $entity_manager = \Drupal::entityManager();
@@ -508,10 +500,6 @@ abstract class Entity implements EntityInterface {
 
   /**
    * {@inheritdoc}
-   *
-   * @return static[]
-   *   An array of entity objects indexed by their IDs. Returns an empty array
-   *   if no matching entities are found.
    */
   public static function loadMultiple(array $ids = NULL) {
     $entity_manager = \Drupal::entityManager();
@@ -520,9 +508,6 @@ abstract class Entity implements EntityInterface {
 
   /**
    * {@inheritdoc}
-   *
-   * @return static
-   *   The entity object.
    */
   public static function create(array $values = array()) {
     $entity_manager = \Drupal::entityManager();

core/lib/Drupal/Core/Entity/EntityAccessControlHandler.php

@@ -206,6 +206,7 @@ class EntityAccessControlHandler extends EntityHandlerBase implements EntityAcce
   public function createAccess($entity_bundle = NULL, AccountInterface $account = NULL, array $context = array(), $return_as_object = FALSE) {
     $account = $this->prepareUser($account);
     $context += array(
+      'entity_type_id' => $this->entityTypeId,
       'langcode' => LanguageInterface::LANGCODE_DEFAULT,
     );
 

core/lib/Drupal/Core/Entity/EntityInterface.php

@@ -113,7 +113,7 @@ interface EntityInterface extends AccessibleInterface, CacheableDependencyInterf
    *   The URL object.
    *
    * @deprecated in Drupal 8.0.0, intended to be removed in Drupal 9.0.0
-   *   Use toUrl() instead.
+   *   Use \Drupal\Core\Entity\EntityInterface::toUrl() instead.
    *
    * @see \Drupal\Core\Entity\EntityInterface::toUrl
    */

core/lib/Drupal/Core/Entity/Plugin/DataType/EntityReference.php

@@ -41,7 +41,7 @@ class EntityReference extends DataReferenceBase {
   /**
    * The entity ID.
    *
-   * @var integer|string
+   * @var int|string
    */
   protected $id;
 

core/lib/Drupal/Core/Entity/Plugin/EntityReferenceSelection/DefaultSelection.php

@@ -257,7 +257,7 @@ class DefaultSelection extends PluginBase implements SelectionInterface, Selecti
     $entities = $this->entityManager->getStorage($target_type)->loadMultiple($result);
     foreach ($entities as $entity_id => $entity) {
       $bundle = $entity->bundle();
-      $options[$bundle][$entity_id] = Html::escape($entity->label());
+      $options[$bundle][$entity_id] = Html::escape($this->entityManager->getTranslationFromContext($entity)->label());
     }
 
     return $options;

core/lib/Drupal/Core/Entity/entity.api.php

@@ -592,7 +592,8 @@ function hook_ENTITY_TYPE_access(\Drupal\Core\Entity\EntityInterface $entity, $o
  *   The account trying to access the entity.
  * @param array $context
  *   An associative array of additional context values. By default it contains
- *   language:
+ *   language and the entity type ID:
+ *   - entity_type_id - the entity type ID.
  *   - langcode - the current language code.
  * @param string $entity_bundle
  *   The entity bundle name.
@@ -1964,7 +1965,7 @@ function hook_ENTITY_TYPE_field_values_init(\Drupal\Core\Entity\FieldableEntityI
  *
  * @return array
  *   The array structure is identical to that of the return value of
- *   \Drupal\Core\Entity\EntityManagerInterface::getExtraFields().
+ *   \Drupal\Core\Entity\EntityFieldManagerInterface::getExtraFields().
  */
 function hook_entity_extra_field_info() {
   $extra = array();

core/lib/Drupal/Core/EventSubscriber/DefaultExceptionHtmlSubscriber.php

@@ -70,7 +70,7 @@ class DefaultExceptionHtmlSubscriber extends HttpExceptionSubscriberBase {
   }
 
   /**
-   * {@inheritDoc}
+   * {@inheritdoc}
    */
   protected function getHandledFormats() {
     return ['html'];

core/lib/Drupal/Core/EventSubscriber/EarlyRenderingControllerWrapperSubscriber.php

@@ -160,8 +160,8 @@ class EarlyRenderingControllerWrapperSubscriber implements EventSubscriberInterf
       }
       else {
         // A Response or domain object is returned that does not care about
-        // attachments nor cacheability. E.g. a RedirectResponse. It is safe to
+        // attachments nor cacheability; for instance, a RedirectResponse. It is
-        // discard any early rendering metadata.
+        // safe to discard any early rendering metadata.
       }
     }
 

core/lib/Drupal/Core/EventSubscriber/ExceptionJsonSubscriber.php

@@ -17,7 +17,7 @@ use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
 class ExceptionJsonSubscriber extends HttpExceptionSubscriberBase {
 
   /**
-   * {@inheritDoc}
+   * {@inheritdoc}
    */
   protected function getHandledFormats() {
     return ['json'];

core/lib/Drupal/Core/EventSubscriber/ExceptionTestSiteSubscriber.php

@@ -23,7 +23,7 @@ class ExceptionTestSiteSubscriber extends HttpExceptionSubscriberBase {
   }
 
   /**
-   * {@inheritDoc}
+   * {@inheritdoc}
    */
   protected function getHandledFormats() {
     return ['html'];

core/lib/Drupal/Core/EventSubscriber/Fast404ExceptionHtmlSubscriber.php

@@ -59,7 +59,7 @@ class Fast404ExceptionHtmlSubscriber extends HttpExceptionSubscriberBase {
   }
 
   /**
-   * {@inheritDoc}
+   * {@inheritdoc}
    */
   protected function getHandledFormats() {
     return ['html'];

core/lib/Drupal/Core/Extension/ExtensionDiscovery.php

@@ -15,6 +15,13 @@ use Symfony\Component\HttpFoundation\Request;
 
 /**
  * Discovers available extensions in the filesystem.
+ *
+ * To also discover test modules, add
+ * @code
+ * $settings['extension_discovery_scan_tests'] = TRUE;
+ * @encode
+ * to your settings.php.
+ *
  */
 class ExtensionDiscovery {
 
@@ -134,6 +141,12 @@ class ExtensionDiscovery {
    * - the site-wide directory; i.e., /
    * - the site-specific directory; e.g., /sites/example.com
    *
+   * To also find test modules, add
+   * @code
+   * $settings['extension_discovery_scan_tests'] = TRUE;
+   * @encode
+   * to your settings.php.
+   *
    * The information is returned in an associative array, keyed by the extension
    * name (without .info.yml extension). Extensions found later in the search
    * will take precedence over extensions found earlier - unless they are not

core/lib/Drupal/Core/Extension/ModuleInstallerInterface.php

@@ -23,6 +23,12 @@ interface ModuleInstallerInterface {
    *   - Invoke hook_install() and add it to the list of installed modules.
    * - Invoke hook_modules_installed().
    *
+   * To install test modules add
+   * @code
+   * $settings['extension_discovery_scan_tests'] = TRUE;
+   * @encode
+   * to your settings.php.
+   *
    * @param string[] $module_list
    *   An array of module names.
    * @param bool $enable_dependencies

core/lib/Drupal/Core/Extension/ThemeHandler.php

@@ -19,9 +19,12 @@ class ThemeHandler implements ThemeHandlerInterface {
    * Contains the features enabled for themes by default.
    *
    * @var array
+   *
+   * @see _system_default_theme_features()
    */
   protected $defaultFeatures = array(
     'favicon',
+    'logo',
     'node_user_picture',
     'comment_user_picture',
     'comment_user_verification',

core/lib/Drupal/Core/Field/FieldFilteredMarkup.php

@@ -61,7 +61,7 @@ final class FieldFilteredMarkup implements MarkupInterface, \Countable {
    *   A list of allowed tags.
    */
   public static function allowedTags() {
-    return ['a', 'b', 'big', 'code', 'del', 'em', 'i', 'ins',  'pre', 'q', 'small', 'span', 'strong', 'sub', 'sup', 'tt', 'ol', 'ul', 'li', 'p', 'br', 'img'];
+    return ['a', 'b', 'big', 'code', 'del', 'em', 'i', 'ins', 'pre', 'q', 'small', 'span', 'strong', 'sub', 'sup', 'tt', 'ol', 'ul', 'li', 'p', 'br', 'img'];
   }
 
   /**

core/lib/Drupal/Core/Field/FieldItemList.php

@@ -115,7 +115,7 @@ class FieldItemList extends ItemList implements FieldItemListInterface {
    * {@inheritdoc}
    */
   public function setValue($values, $notify = TRUE) {
-    // Support passing in only the value of the first item, either as a litteral
+    // Support passing in only the value of the first item, either as a literal
     // (value of the first property) or as an array of properties.
     if (isset($values) && (!is_array($values) || (!empty($values) && !is_numeric(current(array_keys($values)))))) {
       $values = array(0 => $values);

core/lib/Drupal/Core/Field/FieldTypePluginManager.php

@@ -156,7 +156,7 @@ class FieldTypePluginManager extends DefaultPluginManager implements FieldTypePl
   }
 
   /**
-   * @inheritdoc
+   * {@inheritdoc}
    */
   public function getPluginClass($type) {
     $plugin_definition = $this->getDefinition($type, FALSE);

core/lib/Drupal/Core/Field/FormatterPluginManager.php

@@ -136,7 +136,7 @@ class FormatterPluginManager extends DefaultPluginManager {
    *
    * @param string $field_type
    *   The field type.
-   * @param array $properties
+   * @param array $configuration
    *   An array of formatter configuration.
    *
    * @return array

core/lib/Drupal/Core/Field/Plugin/DataType/Deriver/FieldItemDeriver.php

@@ -42,7 +42,7 @@ class FieldItemDeriver implements ContainerDeriverInterface {
    *
    * @param string $base_plugin_id
    *   The base plugin ID.
-   * @param \Drupal\Core\Field\FieldTypePluginManagerInterface $field_type_manager
+   * @param \Drupal\Core\Field\FieldTypePluginManagerInterface $field_type_plugin_manager
    *   The field type plugin manager.
    */
   public function __construct($base_plugin_id, FieldTypePluginManagerInterface $field_type_plugin_manager) {

core/lib/Drupal/Core/Field/Plugin/Field/FieldFormatter/EntityReferenceEntityFormatter.php

@@ -52,8 +52,6 @@ class EntityReferenceEntityFormatter extends EntityReferenceFormatterBase implem
    *   The view mode.
    * @param array $third_party_settings
    *   Any third party settings settings.
-   * @param \Drupal\Core\Entity\EntityManagerInterface $entity_manager
-   *   The entity manager.
    * @param LoggerChannelFactoryInterface $logger_factory
    *   The logger factory.
    */

core/lib/Drupal/Core/FileTransfer/FTPExtension.php

@@ -30,7 +30,7 @@ class FTPExtension extends FTP implements ChmodInterface {
    * {@inheritdoc}
    */
   protected function copyFileJailed($source, $destination) {
-    if (!@ftp_put($this->connection,  $destination, $source, FTP_BINARY)) {
+    if (!@ftp_put($this->connection, $destination, $source, FTP_BINARY)) {
       throw new FileTransferException("Cannot move @source to @destination", NULL, array("@source" => $source, "@destination" => $destination));
     }
   }

core/lib/Drupal/Core/Form/FormState.php

@@ -212,9 +212,8 @@ class FormState implements FormStateInterface {
    *
    * The validation functions and submit functions use this array for nearly all
    * their decision making. (Note that #tree determines whether the values are a
-   * flat array or an array whose structure parallels the $form array. See the
+   * flat array or an array whose structure parallels the $form array. See
-   * @link forms_api_reference.html Form API reference @endlink for more
+   * \Drupal\Core\Render\Element\FormElement for more information.)
-   * information.)
    *
    * This property is uncacheable.
    *

core/lib/Drupal/Core/Form/FormValidator.php

@@ -346,7 +346,7 @@ class FormValidator implements FormValidatorInterface {
         foreach ($value as $v) {
           if (!isset($options[$v])) {
             $form_state->setError($elements, $this->t('An illegal choice has been detected. Please contact the site administrator.'));
-            $this->logger->error('Illegal choice %choice in !name element.', array('%choice' => $v, '!name' => empty($elements['#title']) ? $elements['#parents'][0] : $elements['#title']));
+            $this->logger->error('Illegal choice %choice in %name element.', array('%choice' => $v, '%name' => empty($elements['#title']) ? $elements['#parents'][0] : $elements['#title']));
           }
         }
       }

core/lib/Drupal/Core/Form/form.api.php

@@ -53,7 +53,7 @@
  *     such as how many total items were processed.
  */
 function callback_batch_operation($MULTIPLE_PARAMS, &$context) {
-  $node_storage = $this->container->get('entity.manager')->getStorage('node');
+  $node_storage = \Drupal::entityTypeManager()->getStorage('node');
 
   if (!isset($context['sandbox']['progress'])) {
     $context['sandbox']['progress'] = 0;
@@ -194,7 +194,8 @@ function hook_ajax_render_alter(array &$data) {
  *
  * @see hook_form_BASE_FORM_ID_alter()
  * @see hook_form_FORM_ID_alter()
- * @see forms_api_reference.html
+ *
+ * @ingroup form_api
  */
 function hook_form_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {
   if (isset($form['type']) && $form['type']['#value'] . '_node_settings' == $form_id) {
@@ -237,7 +238,8 @@ function hook_form_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_stat
  * @see hook_form_alter()
  * @see hook_form_BASE_FORM_ID_alter()
  * @see \Drupal\Core\Form\FormBuilderInterface::prepareForm()
- * @see forms_api_reference.html
+ *
+ * @ingroup form_api
  */
 function hook_form_FORM_ID_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {
   // Modification for the form with the given form ID goes here. For example, if
@@ -286,6 +288,8 @@ function hook_form_FORM_ID_alter(&$form, \Drupal\Core\Form\FormStateInterface $f
  * @see hook_form_alter()
  * @see hook_form_FORM_ID_alter()
  * @see \Drupal\Core\Form\FormBuilderInterface::prepareForm()
+ *
+ * @ingroup form_api
  */
 function hook_form_BASE_FORM_ID_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {
   // Modification for the form with the given BASE_FORM_ID goes here. For

core/lib/Drupal/Core/Image/ImageInterface.php

@@ -86,9 +86,12 @@ interface ImageInterface {
    * @param string $operation
    *   The operation to be performed against the image.
    * @param array $arguments
-   *   An associative array of arguments to be passed to the toolkit
+   *   (optional) An associative array of arguments to be passed to the toolkit
-   *   operation, e.g. array('width' => 50, 'height' => 100,
+   *   operation; for instance,
-   *   'upscale' => TRUE).
+   *   @code
+   *     ['width' => 50, 'height' => 100, 'upscale' => TRUE]
+   *   @endcode
+   *   Defaults to an empty array.
    *
    * @return bool
    *   TRUE on success, FALSE on failure.
@@ -120,11 +123,11 @@ interface ImageInterface {
    * @param int $height
    *   The height of the new image, in pixels.
    * @param string $extension
-   *   (Optional) The extension of the image file (e.g. 'png', 'gif', etc.).
+   *   (optional) The extension of the image file (for instance, 'png', 'gif',
-   *   Allowed values depend on the implementation of the image toolkit.
+   *   etc.). Allowed values depend on the implementation of the image toolkit.
    *   Defaults to 'png'.
    * @param string $transparent_color
-   *   (Optional) The hexadecimal string representing the color to be used
+   *   (optional) The hexadecimal string representing the color to be used
    *   for transparency, needed for GIF images. Defaults to '#ffffff' (white).
    *
    * @return bool
@@ -176,8 +179,8 @@ interface ImageInterface {
    * extension.
    *
    * @param string $extension
-   *   The extension to convert to (e.g. 'jpeg' or 'png'). Allowed values depend
+   *   The extension to convert to (for instance, 'jpeg' or 'png'). Allowed
-   *   on the current image toolkit.
+   *   values depend on the current image toolkit.
    *
    * @return bool
    *   TRUE on success, FALSE on failure.
@@ -231,10 +234,10 @@ interface ImageInterface {
    *   The number of (clockwise) degrees to rotate the image.
    * @param string|null $background
    *   (optional) An hexadecimal integer specifying the background color to use
-   *   for the uncovered area of the image after the rotation. E.g. 0x000000 for
+   *   for the uncovered area of the image after the rotation; for example,
-   *   black, 0xff00ff for magenta, and 0xffffff for white. For images that
+   *   0x000000 for black, 0xff00ff for magenta, and 0xffffff for white. When
-   *   support transparency, this will default to transparent. Otherwise it will
+   *   NULL (the default) is specified, for images that support transparency,
-   *   be white.
+   *   this will default to transparent; otherwise, it will default to white.
    *
    * @return bool
    *   TRUE on success, FALSE on failure.

core/lib/Drupal/Core/Language/Language.php

@@ -7,6 +7,8 @@
 
 namespace Drupal\Core\Language;
 
+use Drupal\Core\StringTranslation\TranslatableMarkup;
+
 /**
  * An object containing the information for an interface language.
  *
@@ -151,7 +153,17 @@ class Language implements LanguageInterface {
       $a_weight = $a->getWeight();
       $b_weight = $b->getWeight();
       if ($a_weight == $b_weight) {
-        return strnatcasecmp($a->getName(), $b->getName());
+        $a_name = $a->getName();
+        $b_name = $b->getName();
+        // If either name is a TranslatableMarkup object it can not be converted
+        // to a string. This is because translation requires a sorted list of
+        // languages thereby causing an infinite loop. Determine the order based
+        // on ID if this is the case.
+        if ($a_name instanceof TranslatableMarkup || $b_name instanceof TranslatableMarkup) {
+          $a_name = $a->getId();
+          $b_name = $b->getId();
+        }
+        return strnatcasecmp($a_name, $b_name);
       }
       return ($a_weight < $b_weight) ? -1 : 1;
     });

core/lib/Drupal/Core/Language/LanguageManager.php

@@ -224,7 +224,7 @@ class LanguageManager implements LanguageManagerInterface {
   }
 
   /**
-   * @inheritdoc
+   * {@inheritdoc}
    */
   public static function getStandardLanguageList() {
     // This list is based on languages available from localize.drupal.org. See

core/lib/Drupal/Core/Link.php

@@ -140,11 +140,15 @@ class Link implements RenderableInterface {
   /**
    * Generates the HTML for this Link object.
    *
+   * Do not use this method to render a link in an HTML context. In an HTML
+   * context, self::toRenderable() should be used so that render cache
+   * information is maintained. However, there might be use cases such as tests
+   * and non-HTML contexts where calling this method directly makes sense.
+   *
    * @return \Drupal\Core\GeneratedLink
    *   The link HTML markup.
    *
-   * @deprecated in Drupal 8.0.x-dev, will be removed before Drupal 9.0.0. Use
+   * @see \Drupal\Core\Link::toRenderable()
-   *   self::toRenderable() instead.
    */
   public function toString() {
     return $this->getLinkGenerator()->generateFromLink($this);

core/lib/Drupal/Core/Mail/MailFormatHelper.php

@@ -297,8 +297,8 @@ class MailFormatHelper {
    * Note that we are skipping MIME content header lines, because attached
    * files, especially applications, could have long MIME types or long
    * filenames which result in line length longer than the 77 characters limit
-   * and wrapping that line will break the email format. E.g., the attached file
+   * and wrapping that line will break the email format. For instance, the
-   * hello_drupal.docx will produce the following Content-Type:
+   * attached file hello_drupal.docx will produce the following Content-Type:
    * @code
    * Content-Type:
    * application/vnd.openxmlformats-officedocument.wordprocessingml.document;

core/lib/Drupal/Core/Plugin/Context/ContextInterface.php

@@ -32,9 +32,9 @@ interface ContextInterface extends ComponentContextInterface, CacheableDependenc
   /**
    * Adds a dependency on an object: merges its cacheability metadata.
    *
-   * E.g. when a context depends on some configuration, an entity, or an access
+   * For example, when a context depends on some configuration, an entity, or an
-   * result, we must make sure their cacheability metadata is present on the
+   * access result, we must make sure their cacheability metadata is present on
-   * response. This method makes doing that simple.
+   * the response. This method makes doing that simple.
    *
    * @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $dependency
    *   The dependency. If the object implements CacheableDependencyInterface,

core/lib/Drupal/Core/Plugin/DefaultPluginManager.php

@@ -289,7 +289,7 @@ class DefaultPluginManager extends PluginManagerBase implements PluginManagerInt
    * Invokes the hook to alter the definitions if the alter hook is set.
    *
    * @param $definitions
-   *   The discovered plugin defintions.
+   *   The discovered plugin definitions.
    */
   protected function alterDefinitions(&$definitions) {
     if ($this->alterHook) {

core/lib/Drupal/Core/Plugin/Discovery/AnnotatedClassDiscovery.php

@@ -120,13 +120,13 @@ class AnnotatedClassDiscovery extends ComponentAnnotatedClassDiscovery {
     if ($this->namespaceSuffix) {
       foreach ($this->rootNamespacesIterator as $namespace => $dirs) {
         // Append the namespace suffix to the base namespace, to obtain the
-        // plugin namespace. E.g. 'Drupal\Views' may become
+        // plugin namespace; for example, 'Drupal\Views' may become
         // 'Drupal\Views\Plugin\Block'.
         $namespace .= $this->namespaceSuffix;
         foreach ((array) $dirs as $dir) {
           // Append the directory suffix to the PSR-4 base directory, to obtain
-          // the directory where plugins are found.
+          // the directory where plugins are found. For example,
-          // E.g. DRUPAL_ROOT . '/core/modules/views/src' may become
+          // DRUPAL_ROOT . '/core/modules/views/src' may become
           // DRUPAL_ROOT . '/core/modules/views/src/Plugin/Block'.
           $plugin_namespaces[$namespace][] = $dir . $this->directorySuffix;
         }

core/lib/Drupal/Core/Plugin/Discovery/YamlDiscovery.php

@@ -47,8 +47,8 @@ class YamlDiscovery implements DiscoveryInterface {
    * Construct a YamlDiscovery object.
    *
    * @param string $name
-   *   The file name suffix to use for discovery. E.g. 'test' will become
+   *   The file name suffix to use for discovery; for example, 'test' will
-   *   'MODULE.test.yml'.
+   *   become 'MODULE.test.yml'.
    * @param array $directories
    *   An array of directories to scan.
    */

core/lib/Drupal/Core/Plugin/Discovery/YamlDiscoveryDecorator.php

@@ -30,8 +30,8 @@ class YamlDiscoveryDecorator extends YamlDiscovery {
    * @param \Drupal\Component\Plugin\Discovery\DiscoveryInterface $decorated
    *   The discovery object that is being decorated.
    * @param string $name
-   *   The file name suffix to use for discovery. E.g. 'test' will become
+   *   The file name suffix to use for discovery; for instance, 'test' will
-   *   'MODULE.test.yml'.
+   *   become 'MODULE.test.yml'.
    * @param array $directories
    *   An array of directories to scan.
    */

core/lib/Drupal/Core/Plugin/PluginFormInterface.php

@@ -27,8 +27,7 @@ interface PluginFormInterface {
    * callback and build the rest of the form in the callback. By the time the
    * callback is executed, the element's #parents and #array_parents properties
    * will have been set by the form API. For more documentation on #parents and
-   * #array_parents, see
+   * #array_parents, see \Drupal\Core\Render\Element\FormElement.
-   * https://api.drupal.org/api/drupal/developer!topics!forms_api_reference.html/8.
    *
    * @param array $form
    *   An associative array containing the initial structure of the plugin form.

core/lib/Drupal/Core/Render/Element/HtmlTag.php

@@ -16,6 +16,24 @@ use Drupal\Core\Template\Attribute;
 /**
  * Provides a render element for any HTML tag, with properties and value.
  *
+ * Properties:
+ * - #tag: The tag name to output.
+ * - #attributes: (array, optional) HTML attributes to apply to the tag. The
+ *   attributes are escaped, see \Drupal\Core\Template\Attribute.
+ * - #value: (string, optional) A string containing the textual contents of
+ *   the tag.
+ * - #noscript: (bool, optional) When set to TRUE, the markup
+ *   (including any prefix or suffix) will be wrapped in a <noscript> element.
+ *
+ * Usage example:
+ * @code
+ * $build['hello'] = [
+ *   '#type' => 'html_tag'
+ *   '#tag' => 'p',
+ *   '#value' => $this->t('Hello World'),
+ * ];
+ * @endcode
+ *
  * @RenderElement("html_tag")
  */
 class HtmlTag extends RenderElement {

core/lib/Drupal/Core/Render/Element/InlineTemplate.php

@@ -10,6 +10,22 @@ namespace Drupal\Core\Render\Element;
 /**
  * Provides a render element where the user supplies an in-line Twig template.
  *
+ * Properties:
+ * - #template: The inline Twig template used to render the element.
+ * - #context: (array) The variables to substitute into the Twig template.
+ *   Each variable may be a string or a render array.
+ *
+ * Usage example:
+ * @code
+ * $build['hello']  = [
+ *   '#type' => 'inline_template',
+ *   '#template' => "{% trans %} Hello {% endtrans %} <strong>{{name}}</strong>",
+ *   '#context' => [
+ *     'name' => $name,
+ *   ]
+ * ];
+ * @endcode
+ *
  * @RenderElement("inline_template")
  */
 class InlineTemplate extends RenderElement {

core/lib/Drupal/Core/Render/Element/Label.php

@@ -11,7 +11,8 @@ namespace Drupal\Core\Render\Element;
  * Provides a render element for displaying the label for a form element.
  *
  * Labels are generated automatically from element properties during processing
- * of most form elements.
+ * of most form elements. This element is used internally by the form system
+ * to render labels for form elements.
  *
  * @RenderElement("label")
  */

core/lib/Drupal/Core/Render/Element/Link.php

@@ -15,6 +15,20 @@ use Drupal\Core\Url as CoreUrl;
 /**
  * Provides a link render element.
  *
+ * Properties:
+ * - #title: The link text.
+ * - #url: \Drupal\Url object containing URL information pointing to a internal
+ *   or external link . See \Drupal\Core\Utility\LinkGeneratorInterface.
+ *
+ * Usage example:
+ * @code
+ * $build['examples_link'] = [
+ *   '#title' => $this->t('Examples'),
+ *   '#type' => 'link',
+ *   '#url' => Url::fromRoute('examples.description')
+ * ];
+ * @endcode
+ *
  * @RenderElement("link")
  */
 class Link extends RenderElement {

core/lib/Drupal/Core/Render/Element/MoreLink.php

@@ -10,6 +10,19 @@ namespace Drupal\Core\Render\Element;
 /**
  * Provides a link render element for a "more" link, like those used in blocks.
  *
+ * Properties:
+ * - #title: The text of the link to generate (defaults to 'More').
+ *
+ * See \Drupal\Core\Render\Element\Link for additional properties.
+ *
+ * Usage Example:
+ * @code
+ * $build['more'] = [
+ *   '#type' => 'more_link',
+ *   '#url' => Url::fromRoute('examples.more_examples')
+ * ]
+ * @endcode
+ *
  * @RenderElement("more_link")
  */
 class MoreLink extends Link {

core/lib/Drupal/Core/Render/Element/Pager.php

@@ -12,6 +12,29 @@ use Drupal\Core\Render\Element;
 /**
  * Provides a render element for a pager.
  *
+ * The pager must be initialized with a call to pager_default_initialize() in
+ * order to render properly. When used with database queries, this is performed
+ * for you when you extend a select query with
+ * \Drupal\Core\Database\Query\PagerSelectExtender.
+ *
+ * Properties:
+ * - #element: (optional, int) The pager ID, to distinguish between multiple
+ *   pagers on the same page (defaults to 0).
+ * - #parameters: (optional) An associative array of query string parameters to
+ *   append to the pager.
+ * - #quantity: The maximum number of numbered page links to create (defaults
+ *   to 9).
+ * - #tags: (optional) An array of labels for the controls in the pages.
+ * - #route_name: (optional) The name of the route to be used to build pager
+ *   links. Defaults to '<none>', which will make links relative to the current
+ *   URL. This makes the page more effectively cacheable.
+ *
+ * @code
+ * $build['pager'] = [
+ *   '#type' => 'pager',
+ * ];
+ * @endcode
+ *
  * @RenderElement("pager")
  */
 class Pager extends RenderElement{

core/lib/Drupal/Core/Render/Element/Select.php

@@ -14,12 +14,30 @@ use Drupal\Core\Render\Element;
  * Provides a form element for a drop-down menu or scrolling selection box.
  *
  * Properties:
- * - #options: An associative array, where the keys are the retured values for
+ * - #options: An associative array, where the keys are the values for each
- *   each option, and the values are the options to be shown in the drop-down
+ *   option, and the values are the option labels to be shown in the drop-down
- *   list.
+ *   list. If a value is an array, it will be rendered similarly, but as an
+ *   optgroup. The key of the sub-array will be used as the label for the
+ *   optgroup. Nesting optgroups is not allowed.
  * - #empty_option: The label that will be displayed to denote no selection.
  * - #empty_value: The value of the option that is used to denote no selection.
  *
+ * Usage example:
+ * @code
+ * $form['example_select'] = [
+ *   '#type' => 'select',
+ *   '#title' => t('Select element'),
+ *   '#options' => [
+ *     '1' => t('One'),
+ *     '2' => [
+ *       '2.1' => t('Two point one'),
+ *       '2.2' => t('Two point two'),
+ *     ],
+ *     '3' => t('Three'),
+ *   ],
+ * ];
+ * @endcode
+ *
  * @FormElement("select")
  */
 class Select extends FormElement {

core/lib/Drupal/Core/Render/Element/StatusMessages.php

@@ -10,6 +10,15 @@ namespace Drupal\Core\Render\Element;
 /**
  * Provides a messages element.
  *
+ * Used to display results of drupal_set_message() calls.
+ *
+ * Usage example:
+ * @code
+ * $build['status_messages'] = [
+ *   '#type' => 'status_messages',
+ * ];
+ * @end
+ *
  * @RenderElement("status_messages")
  */
 class StatusMessages extends RenderElement {

core/lib/Drupal/Core/Render/Element/SystemCompactLink.php

@@ -11,7 +11,14 @@ use Drupal\Core\Url as BaseUrl;
 use Drupal\Component\Utility\NestedArray;
 
 /**
- * Provides a link render element to show or hide inline help descriptions.
+ * Provides a link to show or hide help text on administration pages.
+ *
+ * Usage example:
+ * @code
+ * $form['system_compact_link'] = [
+ *   '#type' => 'system_compact_link',
+ * ];
+ * @endcode
  *
  * @RenderElement("system_compact_link")
  */

core/lib/Drupal/Core/Render/PlaceholderGenerator.php

@@ -49,19 +49,19 @@ class PlaceholderGenerator implements PlaceholderGeneratorInterface {
    * {@inheritdoc}
    */
   public function shouldAutomaticallyPlaceholder(array $element) {
+    // Auto-placeholder if the max-age, cache context or cache tag is specified
+    // in the auto-placeholder conditions in the 'renderer.config' container
+    // parameter.
     $conditions = $this->rendererConfig['auto_placeholder_conditions'];
 
-    // Auto-placeholder if max-age is at or below the configured threshold.
     if (isset($element['#cache']['max-age']) && $element['#cache']['max-age'] !== Cache::PERMANENT && $element['#cache']['max-age'] <= $conditions['max-age']) {
       return TRUE;
     }
 
-    // Auto-placeholder if a high-cardinality cache context is set.
     if (isset($element['#cache']['contexts']) && array_intersect($element['#cache']['contexts'], $conditions['contexts'])) {
       return TRUE;
     }
 
-    // Auto-placeholder if a high-invalidation frequency cache tag is set.
     if (isset($element['#cache']['tags']) && array_intersect($element['#cache']['tags'], $conditions['tags'])) {
       return TRUE;
     }

core/lib/Drupal/Core/Render/PlaceholderGeneratorInterface.php

@@ -35,6 +35,11 @@ interface PlaceholderGeneratorInterface {
   /**
    * Whether the given render array should be automatically placeholdered.
    *
+   * The render array should be placeholdered if its cacheability either has a
+   * cache context with too high cardinality, a cache tag with a too high
+   * invalidation rate, or a max-age that is too low. Either of these would make
+   * caching ineffective, and thus we choose to placeholder instead.
+   *
    * @param array $element
    *   The render array whose cacheability to analyze.
    *

core/lib/Drupal/Core/Render/RendererInterface.php

@@ -42,9 +42,9 @@ interface RendererInterface {
    *
    * Calls ::render() in such a way that placeholders are replaced.
    *
-   * Useful for e.g. rendering the values of tokens or emails, which need a
+   * Useful for instance when rendering the values of tokens or emails, which
-   * render array being turned into a string, but don't need any of the
+   * need a render array being turned into a string, but do not need any of the
-   * bubbleable metadata (the attached assets the cache tags).
+   * bubbleable metadata (the attached assets and cache tags).
    *
    * Some of these are a relatively common use case and happen *within* a
    * ::renderRoot() call, but that is generally highly problematic (and hence an
@@ -138,8 +138,8 @@ interface RendererInterface {
    *     - 'keys': An array of one or more keys that identify the element. If
    *       'keys' is set, the cache ID is created automatically from these keys.
    *     - 'contexts': An array of one or more cache context IDs. These are
-   *       converted to a final value depending on the request. (e.g. 'user' is
+   *       converted to a final value depending on the request. (For instance,
-   *       mapped to the current user's ID.)
+   *       'user' is mapped to the current user's ID.)
    *     - 'max-age': A time in seconds. Zero seconds means it is not cacheable.
    *       \Drupal\Core\Cache\Cache::PERMANENT means it is cacheable forever.
    *     - 'bin': Specify a cache bin to cache the element in. Default is
@@ -298,14 +298,14 @@ interface RendererInterface {
    *     placeholder element containing a #lazy_builder function is rendered in
    *     isolation. The resulting markup is used to replace the placeholder, and
    *     any bubbleable metadata is merged.
-   *     Placeholders must be unique, to guarantee that e.g. samples of
+   *     Placeholders must be unique, to guarantee that for instance, samples of
    *     placeholders are not replaced as well.
    *   - Just before finishing the rendering of this element, this element's
    *     stack frame (the topmost one) is bubbled: the two topmost frames are
    *     popped from the stack, they are merged and the result is pushed back
    *     onto the stack.
-   *     So if this element e.g. was a child element, then a new frame was
+   *     So if for instance this element was a child element, then a new frame
-   *     pushed onto the stack element at the beginning of rendering this
+   *     was pushed onto the stack element at the beginning of rendering this
    *     element, it was updated when the rendering was completed, and now we
    *     merge it with the frame for the parent, so that the parent now has the
    *     bubbleable rendering metadata for its child.
@@ -401,9 +401,9 @@ interface RendererInterface {
   /**
    * Adds a dependency on an object: merges its cacheability metadata.
    *
-   * E.g. when a render array depends on some configuration, an entity, or an
+   * For instance, when a render array depends on some configuration, an entity,
-   * access result, we must make sure their cacheability metadata is present on
+   * or an access result, we must make sure their cacheability metadata is
-   * the render array. This method makes doing that simple.
+   * present on the render array. This method makes doing that simple.
    *
    * @param array &$elements
    *   The render array to update.

core/lib/Drupal/Core/Render/theme.api.php

@@ -37,16 +37,16 @@
  * http://twig.sensiolabs.org/doc/templates.html
  *
  * @section sec_theme_hooks Theme Hooks
- * The theme system is invoked in drupal_render() by calling the internal
+ * The theme system is invoked in \Drupal\Core\Render\Renderer::doRender() by
- * _theme() function, which operates on the concept of "theme hooks". Theme
+ * calling the \Drupal\Core\Theme\ThemeManagerInterface::render() function,
- * hooks define how a particular type of data should be rendered. They are
+ * which operates on the concept of "theme hooks". Theme hooks define how a
- * registered by modules by implementing hook_theme(), which specifies the name
+ * particular type of data should be rendered. They are registered by modules by
- * of the hook, the input "variables" used to provide data and options, and
+ * implementing hook_theme(), which specifies the name of the hook, the input
- * other information. Modules implementing hook_theme() also need to provide a
+ * "variables" used to provide data and options, and other information. Modules
- * default implementation for each of their theme hooks, normally in a Twig
+ * implementing hook_theme() also need to provide a default implementation for
- * file, and they may also provide preprocessing functions. For example, the
+ * each of their theme hooks, normally in a Twig file, and they may also provide
- * core Search module defines a theme hook for a search result item in
+ * preprocessing functions. For example, the core Search module defines a theme
- * search_theme():
+ * hook for a search result item in search_theme():
  * @code
  * return array(
  *   'search_result' => array(
@@ -366,7 +366,7 @@
  * @code
  *   '#cache' => [
  *     'keys' => ['entity_view', 'node', $node->id()],
- *     'contexts' => ['language'],
+ *     'contexts' => ['languages'],
  *     'tags' => ['node:' . $node->id()],
  *     'max-age' => Cache::PERMANENT,
  *   ],
@@ -429,9 +429,10 @@
  *
  * @section render_pipeline The render pipeline
  * The term "render pipeline" refers to the process Drupal uses to take
- * information provided by modules and render it into a response. For more
+ * information provided by modules and render it into a response. See
- * details on this process, see https://www.drupal.org/developing/api/8/render;
+ * https://www.drupal.org/developing/api/8/render for more details on this
- * for background on routing concepts, see @ref sec_controller.
+ * process. For background on routing concepts, see
+ * @link routing Routing API. @endlink
  *
  * There are in fact multiple render pipelines:
  * - Drupal always uses the Symfony render pipeline. See
@@ -472,6 +473,36 @@
  * @}
  */
 
+/**
+ * @defgroup listing_page_element Page header for Elements page
+ * @{
+ * Introduction to form and render elements
+ *
+ * Render elements are referenced in render arrays. Render arrays contain data
+ * to be rendered, along with meta-data and attributes that specify how to
+ * render the data into markup; see the
+ * @link theme_render Render API topic @endlink for an overview of render
+ * arrays and render elements. Form arrays are a subset of render arrays,
+ * representing HTML forms; form elements are a subset of render elements,
+ * representing HTML elements for forms. See the
+ * @link form_api Form API topic @endlink for an overview of forms, form
+ * processing, and form arrays.
+ *
+ * Each form and render element type corresponds to an element plugin class;
+ * each of them either extends \Drupal\Core\Render\Element\RenderElement
+ * (render elements) or \Drupal\Core\Render\Element\FormElement (form
+ * elements). Usage and properties are documented on the individual classes,
+ * and the two base classes list common properties shared by all render
+ * elements and the form element subset, respectively.
+ *
+ * @see theme_render
+ * @see form_api
+ * @see \Drupal\Core\Render\Element\RenderElement
+ * @see \Drupal\Core\Render\Element\FormElement
+ *
+ * @}
+ */
+
 /**
  * @addtogroup hooks
  * @{
@@ -512,7 +543,8 @@ function hook_form_system_theme_settings_alter(&$form, \Drupal\Core\Form\FormSta
  * preprocess variables for a specific theme hook, whether implemented as a
  * template or function.
  *
- * For more detailed information, see _theme().
+ * For more detailed information, see the
+ * @link themeable Theme system overview topic @endlink.
  *
  * @param $variables
  *   The variables array (modify in place).
@@ -560,7 +592,8 @@ function hook_preprocess(&$variables, $hook) {
  * hook. It should only be used if a module needs to override or add to the
  * theme preprocessing for a theme hook it didn't define.
  *
- * For more detailed information, see _theme().
+ * For more detailed information, see the
+ * @link themeable Theme system overview topic @endlink.
  *
  * @param $variables
  *   The variables array (modify in place).

core/lib/Drupal/Core/Routing/UrlGenerator.php

@@ -432,7 +432,7 @@ class UrlGenerator implements UrlGeneratorInterface {
   }
 
   /**
-   * {@inheritDoc}
+   * {@inheritdoc}
    */
   public function supports($name) {
     // Support a route object and any string as route name.
@@ -440,7 +440,7 @@ class UrlGenerator implements UrlGeneratorInterface {
   }
 
   /**
-   * {@inheritDoc}
+   * {@inheritdoc}
    */
   public function getRouteDebugMessage($name, array $parameters = array()) {
     if (is_scalar($name)) {

core/lib/Drupal/Core/Session/SessionManager.php

@@ -331,8 +331,7 @@ class SessionManager extends NativeSessionStorage implements SessionManagerInter
    * Migrates the current session to a new session id.
    *
    * @param string $old_session_id
-   *   The old session id. The new session id is $this->getId() unless
+   *   The old session ID. The new session ID is $this->getId().
-   *   $new_insecure_session_id is not empty.
    */
   protected function migrateStoredSession($old_session_id) {
     $fields = array('sid' => Crypt::hashBase64($this->getId()));

core/lib/Drupal/Core/Site/Settings.php

@@ -149,24 +149,24 @@ final class Settings {
   }
 
   /**
-   * Generates a prefix for APC user cache keys.
+   * Generates a prefix for APCu user cache keys.
    *
-   * A standardized prefix is useful to allow visual inspection of an APC user
+   * A standardized prefix is useful to allow visual inspection of an APCu user
    * cache. By default, this method will produce a unique prefix per site using
    * the hash salt. If the setting 'apcu_ensure_unique_prefix' is set to FALSE
    * then if the caller does not provide a $site_path only the Drupal root will
    * be used. This allows WebTestBase to use the same prefix ensuring that the
-   * number of APC items created during a full test run is kept to a minimum.
+   * number of APCu items created during a full test run is kept to a minimum.
    * Additionally, if a multi site implementation does not use site specific
    * module directories setting apcu_ensure_unique_prefix would allow the sites
-   * to share APC cache items.
+   * to share APCu cache items.
    *
    * @param $identifier
    *   An identifier for the prefix. For example, 'class_loader' or
    *   'cache_backend'.
    *
    * @return string
-   *   The prefix for APC user cache keys.
+   *   The prefix for APCu user cache keys.
    */
   public static function getApcuPrefix($identifier, $root, $site_path = '') {
     if (static::get('apcu_ensure_unique_prefix', TRUE)) {

core/lib/Drupal/Core/StreamWrapper/StreamWrapperInterface.php

@@ -66,8 +66,10 @@ interface StreamWrapperInterface extends PhpStreamWrapperInterface {
    */
 
   /**
-   * Not visible in the UI or accessible via web, but readable and writable.
+   * Defines the stream wrapper bit flag for a hidden file.
-   * E.g. the temporary directory for uploads.
+   *
+   * This is not visible in the UI or accessible via web, but readable and
+   * writable; for instance, the temporary directory for file uploads.
    */
   const HIDDEN = 0x000C;
 

core/lib/Drupal/Core/Template/TwigExtension.php

@@ -315,8 +315,8 @@ class TwigExtension extends \Twig_Extension {
    * ampersand ("&") which separates query params. Thus we cannot mark
    * the generated URL as always safe, but only when we are sure there won't be
    * multiple query params. This is the case when there are none or only one
-   * constant parameter given. E.g. we know beforehand this will not need to
+   * constant parameter given. For instance, we know beforehand this will not
-   * be escaped:
+   * need to be escaped:
    * - path('route')
    * - path('route', {'param': 'value'})
    * But the following may need to be escaped:

core/lib/Drupal/Core/Template/TwigSandboxPolicy.php

@@ -81,8 +81,10 @@ class TwigSandboxPolicy implements \Twig_Sandbox_SecurityPolicyInterface {
    * {@inheritdoc}
    */
   public function checkMethodAllowed($obj, $method) {
-    if (isset($this->whitelisted_classes[get_class($obj)])) {
+    foreach ($this->whitelisted_classes as $class => $key) {
-      return TRUE;
+      if ($obj instanceof $class) {
+        return TRUE;
+      }
     }
 
     // Return quickly for an exact match of the method name.

core/lib/Drupal/Core/Template/TwigTransTokenParser.php

@@ -84,7 +84,7 @@ class TwigTransTokenParser extends \Twig_TokenParser {
    *
    * @param \Twig_Node $body
    *   The expression to check.
-   * @param integer $lineno
+   * @param int $lineno
    *   The source line.
    *
    * @throws \Twig_Error_Syntax

core/lib/Drupal/Core/Theme/Registry.php

@@ -47,12 +47,12 @@ class Registry implements DestructableInterface {
    *   - name: The name of the extension the original theme hook originates
    *     from; e.g., 'node' for theme hook 'node' of Node module.
    *   - theme path: The effective \Drupal\Core\Theme\ActiveTheme::getPath()
-   *      during _theme(), available as
+   *      during \Drupal\Core\Theme\ThemeManagerInterface::render(), available
-   *      'directory' variable in templates. For functions, it should point to
+   *      as 'directory' variable in templates. For functions, it should point
-   *      the respective theme.For templates, it should point to the directory
+   *      to the respective theme. For templates, it should point to the
-   *      that contains the template.
+   *      directory that contains the template.
    *   - includes: (optional) An array of include files to load when the theme
-   *     hook is executed by _theme().
+   *     hook is executed by \Drupal\Core\Theme\ThemeManagerInterface::render().
    *   - file: (optional) A filename to add to 'includes', either prefixed with
    *     the value of 'path', or the path of the extension implementing
    *     hook_theme().
@@ -389,7 +389,8 @@ class Registry implements DestructableInterface {
    *     in hook_theme(). If there is more than one implementation and
    *     'render element' is not specified in a later one, then the previous
    *     definition is kept.
-   *   - 'preprocess functions': See _theme() for detailed documentation.
+   *   - See the @link themeable Theme system overview topic @endlink for
+   *     detailed documentation.
    * @param string $name
    *   The name of the module, theme engine, base theme engine, theme or base
    *   theme implementing hook_theme().
@@ -530,7 +531,8 @@ class Registry implements DestructableInterface {
           }
           foreach ($prefixes as $prefix) {
             // Only use non-hook-specific variable preprocessors for theming
-            // hooks implemented as templates. See _theme().
+            // hooks implemented as templates. See the @defgroup themeable
+            // topic.
             if (isset($info['template']) && function_exists($prefix . '_preprocess')) {
               $info['preprocess functions'][] = $prefix . '_preprocess';
             }
@@ -566,7 +568,7 @@ class Registry implements DestructableInterface {
             $cache[$hook]['preprocess functions'] = array();
           }
           // Only use non-hook-specific variable preprocessors for theme hooks
-          // implemented as templates. See _theme().
+          // implemented as templates. See the @defgroup themeable topic.
           if (isset($info['template']) && function_exists($name . '_preprocess')) {
             $cache[$hook]['preprocess functions'][] = $name . '_preprocess';
           }

core/lib/Drupal/Core/Theme/ThemeInitialization.php

@@ -267,7 +267,7 @@ class ThemeInitialization implements ThemeInitializationInterface {
    */
   protected function getExtensions() {
     if (!isset($this->extensions)) {
-      $this->extensions = array_merge($this->moduleHandler->getModuleList(),  $this->themeHandler->listInfo());
+      $this->extensions = array_merge($this->moduleHandler->getModuleList(), $this->themeHandler->listInfo());
     }
     return $this->extensions;
   }

core/lib/Drupal/Core/Theme/ThemeManager.php

@@ -138,11 +138,11 @@ class ThemeManager implements ThemeManagerInterface {
 
     $active_theme = $this->getActiveTheme();
 
-    // If called before all modules are loaded, we do not necessarily have a full
+    // If called before all modules are loaded, we do not necessarily have a
-    // theme registry to work with, and therefore cannot process the theme
+    // full theme registry to work with, and therefore cannot process the theme
     // request properly. See also \Drupal\Core\Theme\Registry::get().
     if (!$this->moduleHandler->isLoaded() && !defined('MAINTENANCE_MODE')) {
-      throw new \Exception(t('_theme() may not be called until all modules are loaded.'));
+      throw new \Exception('The theme implementations may not be rendered until all modules are loaded.');
     }
 
     $theme_registry = $this->themeRegistry->getRuntime();
@@ -180,9 +180,10 @@ class ThemeManager implements ThemeManagerInterface {
           \Drupal::logger('theme')->warning('Theme hook %hook not found.', array('%hook' => $hook));
         }
         // There is no theme implementation for the hook passed. Return FALSE so
-        // the function calling _theme() can differentiate between a hook that
+        // the function calling
-        // exists and renders an empty string and a hook that is not
+        // \Drupal\Core\Theme\ThemeManagerInterface::render() can differentiate
-        // implemented.
+        // between a hook that exists and renders an empty string, and a hook
+        // that is not implemented.
         return FALSE;
       }
     }
@@ -233,8 +234,8 @@ class ThemeManager implements ThemeManagerInterface {
 
     // Invoke hook_theme_suggestions_HOOK().
     $suggestions = $this->moduleHandler->invokeAll('theme_suggestions_' . $base_theme_hook, array($variables));
-    // If _theme() was invoked with a direct theme suggestion like
+    // If the theme implementation was invoked with a direct theme suggestion
-    // '#theme' => 'node__article', add it to the suggestions array before
+    // like '#theme' => 'node__article', add it to the suggestions array before
     // invoking suggestion alter hooks.
     if (isset($info['base hook'])) {
       $suggestions[] = $hook;
@@ -250,10 +251,10 @@ class ThemeManager implements ThemeManagerInterface {
     $this->alter($hooks, $suggestions, $variables, $base_theme_hook);
 
     // Check if each suggestion exists in the theme registry, and if so,
-    // use it instead of the hook that _theme() was called with. For example, a
+    // use it instead of the base hook. For example, a function may use
-    // function may call _theme('node', ...), but a module can add
+    // '#theme' => 'node', but a module can add 'node__article' as a suggestion
-    // 'node__article' as a suggestion via hook_theme_suggestions_HOOK_alter(),
+    // via hook_theme_suggestions_HOOK_alter(), enabling a theme to have
-    // enabling a theme to have an alternate template file for article nodes.
+    // an alternate template file for article nodes.
     foreach (array_reverse($suggestions) as $suggestion) {
       if ($theme_registry->has($suggestion)) {
         $info = $theme_registry->get($suggestion);

core/lib/Drupal/Core/TypedData/Plugin/DataType/Timestamp.php

@@ -23,7 +23,7 @@ class Timestamp extends IntegerData implements DateTimeInterface {
   /**
    * The data value as a UNIX timestamp.
    *
-   * @var integer
+   * @var int
    */
   protected $value;