Drupal
/
drupal
mirror of https://git.drupalcode.org/project/drupal.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Issue #2627018 by Lars Toomre: Some fixes for 'e.g.' in docblocks and code comments

8.1.x
Jennifer Hodgdon 2015-12-03 11:04:31 -08:00
parent 0fb0add63c
commit aaabb05c3d
34 changed files with 204 additions and 177 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
core/CHANGELOG.txt
View File

@ -341,7 +341,7 @@ Drupal 7.0, 2011-01-05
- Improved time zone support: - Improved time zone support:
* Drupal now uses PHP's time zone database when rendering dates in local * 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 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 * In some cases the upgrade and install scripts do not choose the preferred
site default time zone. The automatically-selected time zone can be site default time zone. The automatically-selected time zone can be
corrected at admin/config/regional/settings. corrected at admin/config/regional/settings.
@ -399,7 +399,7 @@ Drupal 7.0, 2011-01-05
preserved but renamed to file_unmanaged_*(). preserved but renamed to file_unmanaged_*().
* Rewrote file handling to use PHP stream wrappers to enable support for * Rewrote file handling to use PHP stream wrappers to enable support for
both public and private files and to support pluggable storage mechanisms 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 * The mime_extension_mapping variable has been removed. Modules that need to
alter the default MIME type extension mappings should implement alter the default MIME type extension mappings should implement
hook_file_mimetype_mapping_alter(). hook_file_mimetype_mapping_alter().
@ -816,7 +816,7 @@ Drupal 4.7.0, 2006-05-01
- Added support for PHP5's 'mysqli' extension. - Added support for PHP5's 'mysqli' extension.
- Search module: - Search module:
* Made indexer smarter and more robust. * 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. * Added customizable result ranking.
- PostgreSQL support: - PostgreSQL support:
* Removed dependency on PL/pgSQL procedural language. * Removed dependency on PL/pgSQL procedural language.

80
core/includes/database.inc
View File

@ -32,8 +32,8 @@ use Drupal\Core\Site\Settings;
* The prepared statement query to run. Although it will accept both named and * The prepared statement query to run. Although it will accept both named and
* unnamed placeholders, named placeholders are strongly preferred as they are * unnamed placeholders, named placeholders are strongly preferred as they are
* more self-documenting. If the argument corresponding to a placeholder is * 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 * @param array $args
* An array of values to substitute into the query. If the query uses named * 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 * 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 * @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 * 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); * $injected_database->query($query, $args, $options);
* *
* @see \Drupal\Core\Database\Connection::query() * @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 * @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 * 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); * $injected_database->queryRange($query, $from, $count, $args, $options);
* *
* @see \Drupal\Core\Database\Connection::queryRange() * @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 * @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 * 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); * $injected_database->queryTemporary($query, $args, $options);
* *
* @see \Drupal\Core\Database\Connection::queryTemporary() * @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 * @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 * 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::insert()
* @see \Drupal\Core\Database\Connection::defaultOptions() * @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 * @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 * 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::merge()
* @see \Drupal\Core\Database\Connection::defaultOptions() * @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 * @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 * 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::update()
* @see \Drupal\Core\Database\Connection::defaultOptions() * @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 * @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 * 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::delete()
* @see \Drupal\Core\Database\Connection::defaultOptions() * @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 * @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 * 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::truncate()
* @see \Drupal\Core\Database\Connection::defaultOptions() * @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 * @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 * 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); * $injected_database->select($table, $alias, $options);
* *
* @see \Drupal\Core\Database\Connection::select() * @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 * @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 * 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); * $injected_database->startTransaction($name);
* *
* @see \Drupal\Core\Database\Connection::startTransaction() * @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 * @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 * 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() * @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 * @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 * 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() * @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 * @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 * 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() * @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 * @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 * 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() * @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 * @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 * 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() * @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 * @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 * 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); * $injected_database->schema()->createTable($name, $table);
* *
* @see \Drupal\Core\Database\Schema::createTable() * @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 * @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 * 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); * $injected_database->schema()->fieldNames($fields);
* *
* @see \Drupal\Core\Database\Schema::fieldNames() * @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 * @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 * 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); * $injected_database->schema()->indexExists($table, $name);
* *
* @see \Drupal\Core\Database\Schema::indexExists() * @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 * @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 * 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); * $injected_database->schema()->tableExists($table);
* *
* @see \Drupal\Core\Database\Schema::tableExists() * @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 * @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 * 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); * $injected_database->schema()->fieldExists($table, $field);
* *
* @see \Drupal\Core\Database\Schema::fieldExists() * @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 * @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 * 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); * $injected_database->schema()->findTables($table_expression);
* *
* @see \Drupal\Core\Database\Schema::findTables() * @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 * @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 * 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); * $injected_database->schema()->renameTable($table, $new_name);
* *
* @see \Drupal\Core\Database\Schema::renameTable() * @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 * @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 * 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); * $injected_database->schema()->dropTable($table);
* *
* @see \Drupal\Core\Database\Schema::dropTable() * @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 * @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 * 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); * $injected_database->schema()->addField($table, $field, $spec, $keys_new);
* *
* @see \Drupal\Core\Database\Schema::addField() * @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 * @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 * 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); * $injected_database->schema()->dropField($table, $field);
* *
* @see \Drupal\Core\Database\Schema::dropField() * @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 * @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 * 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); * $injected_database->schema()->fieldSetDefault($table, $field, $default);
* *
* @see \Drupal\Core\Database\Schema::fieldSetDefault() * @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 * @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 * 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); * $injected_database->schema()->fieldSetNoDefault($table, $field);
* *
* @see \Drupal\Core\Database\Schema::fieldSetNoDefault() * @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 * @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 * 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); * $injected_database->schema()->addPrimaryKey($table, $fields);
* *
* @see \Drupal\Core\Database\Schema::addPrimaryKey() * @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 * @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 * 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); * $injected_database->schema()->dropPrimaryKey($table);
* *
* @see \Drupal\Core\Database\Schema::dropPrimaryKey() * @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 * @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 * 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); * $injected_database->schema()->addUniqueKey($table, $name, $fields);
* *
* @see \Drupal\Core\Database\Schema::addUniqueKey() * @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 * @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 * 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); * $injected_database->schema()->dropUniqueKey($table, $name);
* *
* @see \Drupal\Core\Database\Schema::dropUniqueKey() * @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 * @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 * 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); * $injected_database->schema()->addIndex($table, $name, $fields, $spec);
* *
* @see hook_schema() * @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 * @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 * 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); * $injected_database->schema()->dropIndex($table, $name);
* *
* @see \Drupal\Core\Database\Schema::dropIndex() * @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 * @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 * 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); * $injected_database->schema()->changeField($table, $field, $field_new, $spec, $keys_new);
* *
* @see \Drupal\Core\Database\Schema::changeField() * @see \Drupal\Core\Database\Schema::changeField()

12
core/lib/Drupal.php
View File

@ -423,11 +423,11 @@ class Drupal {
* Returns the entity query object for this entity type. * Returns the entity query object for this entity type.
* *
* @param string $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. * returned.
* @param string $conjunction * @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 * @return \Drupal\Core\Entity\Query\QueryInterface
* The query object that can query the given entity type. * 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. * Returns the entity query aggregate object for this entity type.
* *
* @param string $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. * returned.
* @param string $conjunction * @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 * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
* The query object that can query the given entity type. * The query object that can query the given entity type.

24
core/lib/Drupal/Component/Utility/UrlHelper.php
View File

@ -36,10 +36,11 @@ class UrlHelper {
* http_build_query() directly. * http_build_query() directly.
* *
* @param array $query * @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 * @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 * @return string
* A rawurlencoded string which can be used as or appended to the URL query * A rawurlencoded string which can be used as or appended to the URL query
@ -168,8 +169,8 @@ class UrlHelper {
} }
// Internal URLs. // Internal URLs.
else { 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); $parts = parse_url('http://example.com/' . $url);
// Strip the leading slash that was just added. // Strip the leading slash that was just added.
$options['path'] = substr($parts['path'], 1); $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 * @param string $path
* The internal path or external URL being linked to, such as "node/34" or * 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 * 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 * 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 * 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" * 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 * 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 * Url::fromUri($possibly_not_a_url)->toString(), which either throws an
* exception or returns a well-formed URL. * exception or returns a well-formed URL.
* *

5
core/lib/Drupal/Core/Authentication/AuthenticationProviderFilterInterface.php
View File

@ -13,8 +13,9 @@ use Symfony\Component\HttpFoundation\Request;
* Restrict authentication methods to a subset of the site. * Restrict authentication methods to a subset of the site.
* *
* Some authentication methods should not be available throughout a whole 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 { interface AuthenticationProviderFilterInterface {

6
core/lib/Drupal/Core/Cache/CacheableResponseInterface.php
View File

@ -17,9 +17,9 @@ interface CacheableResponseInterface {
/** /**
* Adds a dependency on an object: merges its cacheability metadata. * 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 * @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $dependency
* The dependency. If the object implements CacheableDependencyInterface, * The dependency. If the object implements CacheableDependencyInterface,

16
core/lib/Drupal/Core/Cache/Context/CacheContextsManager.php
View File

@ -92,9 +92,10 @@ class CacheContextsManager {
* *
* A cache context token is either: * A cache context token is either:
* - a cache context ID (if the service ID is 'cache_context.foo', then 'foo' * - 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 * @param string[] $context_tokens
* An array of cache 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 * If a cache context is being optimized away, it is able to set cacheable
* metadata for itself which will be bubbled up. * 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'] -> ['a']
* - ['a', 'a.b.c'] -> ['a'] * - ['a', 'a.b.c'] -> ['a']
* - ['a.b', 'a.b.c'] -> ['a.b'] * - ['a.b', 'a.b.c'] -> ['a.b']

4
core/lib/Drupal/Core/Config/Entity/ConfigEntityStorageInterface.php
View File

@ -18,10 +18,10 @@ interface ConfigEntityStorageInterface extends EntityStorageInterface {
* Extracts the configuration entity ID from the full configuration name. * Extracts the configuration entity ID from the full configuration name.
* *
* @param string $config_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'. * 'views.view.archive'.
* @param string $config_prefix * @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 * @return string
* The ID of the configuration entity. * The ID of the configuration entity.

6
core/lib/Drupal/Core/Config/InstallStorage.php
View File

@ -80,9 +80,9 @@ class InstallStorage extends FileStorage {
* The path to the configuration file. * The path to the configuration file.
* *
* @todo Improve this when figuring out how we want to handle configuration in * @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) { public function getFilePath($name) {
$folders = $this->getAllFolders(); $folders = $this->getAllFolders();

4
core/lib/Drupal/Core/EventSubscriber/EarlyRenderingControllerWrapperSubscriber.php
View File

@ -160,8 +160,8 @@ class EarlyRenderingControllerWrapperSubscriber implements EventSubscriberInterf
} }
else { else {
// A Response or domain object is returned that does not care about // 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.
} }
} }

27
core/lib/Drupal/Core/Image/ImageInterface.php
View File

@ -86,9 +86,12 @@ interface ImageInterface {
* @param string $operation * @param string $operation
* The operation to be performed against the image. * The operation to be performed against the image.
* @param array $arguments * @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 * @return bool
* TRUE on success, FALSE on failure. * TRUE on success, FALSE on failure.
@ -120,11 +123,11 @@ interface ImageInterface {
* @param int $height * @param int $height
* The height of the new image, in pixels. * The height of the new image, in pixels.
* @param string $extension * @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'. * Defaults to 'png'.
* @param string $transparent_color * @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). * for transparency, needed for GIF images. Defaults to '#ffffff' (white).
* *
* @return bool * @return bool
@ -176,8 +179,8 @@ interface ImageInterface {
* extension. * extension.
* *
* @param string $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 * @return bool
* TRUE on success, FALSE on failure. * TRUE on success, FALSE on failure.
@ -231,10 +234,10 @@ interface ImageInterface {
* The number of (clockwise) degrees to rotate the image. * The number of (clockwise) degrees to rotate the image.
* @param string|null $background * @param string|null $background
* (optional) An hexadecimal integer specifying the background color to use * (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 * @return bool
* TRUE on success, FALSE on failure. * TRUE on success, FALSE on failure.

4
core/lib/Drupal/Core/Mail/MailFormatHelper.php
View File

@ -297,8 +297,8 @@ class MailFormatHelper {
* Note that we are skipping MIME content header lines, because attached * Note that we are skipping MIME content header lines, because attached
* files, especially applications, could have long MIME types or long * files, especially applications, could have long MIME types or long
* filenames which result in line length longer than the 77 characters limit * 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 * @code
* Content-Type: * Content-Type:
* application/vnd.openxmlformats-officedocument.wordprocessingml.document; * application/vnd.openxmlformats-officedocument.wordprocessingml.document;

6
core/lib/Drupal/Core/Plugin/Context/ContextInterface.php
View File

@ -32,9 +32,9 @@ interface ContextInterface extends ComponentContextInterface, CacheableDependenc
/** /**
* Adds a dependency on an object: merges its cacheability metadata. * 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 * @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $dependency
* The dependency. If the object implements CacheableDependencyInterface, * The dependency. If the object implements CacheableDependencyInterface,

6
core/lib/Drupal/Core/Plugin/Discovery/AnnotatedClassDiscovery.php
View File

@ -120,13 +120,13 @@ class AnnotatedClassDiscovery extends ComponentAnnotatedClassDiscovery {
if ($this->namespaceSuffix) { if ($this->namespaceSuffix) {
foreach ($this->rootNamespacesIterator as $namespace => $dirs) { foreach ($this->rootNamespacesIterator as $namespace => $dirs) {
// Append the namespace suffix to the base namespace, to obtain the // 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'. // 'Drupal\Views\Plugin\Block'.
$namespace .= $this->namespaceSuffix; $namespace .= $this->namespaceSuffix;
foreach ((array) $dirs as $dir) { foreach ((array) $dirs as $dir) {
// Append the directory suffix to the PSR-4 base directory, to obtain // 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'. // DRUPAL_ROOT . '/core/modules/views/src/Plugin/Block'.
$plugin_namespaces[$namespace][] = $dir . $this->directorySuffix; $plugin_namespaces[$namespace][] = $dir . $this->directorySuffix;
} }

4
core/lib/Drupal/Core/Plugin/Discovery/YamlDiscovery.php
View File

@ -47,8 +47,8 @@ class YamlDiscovery implements DiscoveryInterface {
* Construct a YamlDiscovery object. * Construct a YamlDiscovery object.
* *
* @param string $name * @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 * @param array $directories
* An array of directories to scan. * An array of directories to scan.
*/ */

4
core/lib/Drupal/Core/Plugin/Discovery/YamlDiscoveryDecorator.php
View File

@ -30,8 +30,8 @@ class YamlDiscoveryDecorator extends YamlDiscovery {
* @param \Drupal\Component\Plugin\Discovery\DiscoveryInterface $decorated * @param \Drupal\Component\Plugin\Discovery\DiscoveryInterface $decorated
* The discovery object that is being decorated. * The discovery object that is being decorated.
* @param string $name * @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 * @param array $directories
* An array of directories to scan. * An array of directories to scan.
*/ */

22
core/lib/Drupal/Core/Render/RendererInterface.php
View File

@ -42,9 +42,9 @@ interface RendererInterface {
* *
* Calls ::render() in such a way that placeholders are replaced. * 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 * Some of these are a relatively common use case and happen *within* a
* ::renderRoot() call, but that is generally highly problematic (and hence an * ::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': An array of one or more keys that identify the element. If
* 'keys' is set, the cache ID is created automatically from these keys. * 'keys' is set, the cache ID is created automatically from these keys.
* - 'contexts': An array of one or more cache context IDs. These are * - '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. * - 'max-age': A time in seconds. Zero seconds means it is not cacheable.
* \Drupal\Core\Cache\Cache::PERMANENT means it is cacheable forever. * \Drupal\Core\Cache\Cache::PERMANENT means it is cacheable forever.
* - 'bin': Specify a cache bin to cache the element in. Default is * - '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 * placeholder element containing a #lazy_builder function is rendered in
* isolation. The resulting markup is used to replace the placeholder, and * isolation. The resulting markup is used to replace the placeholder, and
* any bubbleable metadata is merged. * 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. * placeholders are not replaced as well.
* - Just before finishing the rendering of this element, this element's * - Just before finishing the rendering of this element, this element's
* stack frame (the topmost one) is bubbled: the two topmost frames are * 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 * popped from the stack, they are merged and the result is pushed back
* onto the stack. * 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 * 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 * merge it with the frame for the parent, so that the parent now has the
* bubbleable rendering metadata for its child. * bubbleable rendering metadata for its child.
@ -401,9 +401,9 @@ interface RendererInterface {
/** /**
* Adds a dependency on an object: merges its cacheability metadata. * 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 * @param array &$elements
* The render array to update. * The render array to update.

6
core/lib/Drupal/Core/StreamWrapper/StreamWrapperInterface.php
View File

@ -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; const HIDDEN = 0x000C;

4
core/lib/Drupal/Core/Template/TwigExtension.php
View File

@ -315,8 +315,8 @@ class TwigExtension extends \Twig_Extension {
* ampersand ("&") which separates query params. Thus we cannot mark * 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 * 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 * 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')
* - path('route', {'param': 'value'}) * - path('route', {'param': 'value'})
* But the following may need to be escaped: * But the following may need to be escaped:

22
core/lib/Drupal/Core/TypedData/TypedDataManagerInterface.php
View File

@ -78,7 +78,7 @@ interface TypedDataManagerInterface extends PluginManagerInterface, CachedDiscov
* class used by a data type is known, this method allows the creation of data * class used by a data type is known, this method allows the creation of data
* definitions for any given data type. * definitions for any given data type.
* *
* E.g., if a definition for a map is to be created, the following code * For example, if a definition for a map is to be created, the following code
* could be used instead of calling this method with the argument 'map': * could be used instead of calling this method with the argument 'map':
* @code * @code
* $map_definition = \Drupal\Core\TypedData\MapDataDefinition::create(); * $map_definition = \Drupal\Core\TypedData\MapDataDefinition::create();
@ -137,9 +137,10 @@ interface TypedDataManagerInterface extends PluginManagerInterface, CachedDiscov
* Get a typed data instance for a property of a given typed data object. * Get a typed data instance for a property of a given typed data object.
* *
* This method will use prototyping for fast and efficient instantiation of * This method will use prototyping for fast and efficient instantiation of
* many property objects with the same property path; e.g., * many property objects with the same property path; for example,
* when multiple comments are used comment_body.0.value needs to be * when multiple comments are used comment_body.0.value needs to be
* instantiated very often. * instantiated very often.
*
* Prototyping is done by the root object's data type and the given * Prototyping is done by the root object's data type and the given
* property path, i.e. all property instances having the same property path * property path, i.e. all property instances having the same property path
* and inheriting from the same data type are prototyped. * and inheriting from the same data type are prototyped.
@ -203,9 +204,10 @@ interface TypedDataManagerInterface extends PluginManagerInterface, CachedDiscov
* Gets default constraints for the given data definition. * Gets default constraints for the given data definition.
* *
* This generates default constraint definitions based on the data definition; * This generates default constraint definitions based on the data definition;
* e.g. a NotNull constraint is generated if the data is defined as required. * for example, a NotNull constraint is generated if the data is defined as
* Besides that any constraints defined for the data type, i.e. below the * required. Besides that, any constraints defined for the data type (that is,
* 'constraint' key of the type's plugin definition, are taken into account. * below the 'constraint' key of the type's plugin definition) are taken into
* account.
* *
* @param \Drupal\Core\TypedData\DataDefinitionInterface $definition * @param \Drupal\Core\TypedData\DataDefinitionInterface $definition
* A data definition. * A data definition.
@ -222,12 +224,12 @@ interface TypedDataManagerInterface extends PluginManagerInterface, CachedDiscov
* *
* The canonical representation is typically used when data is passed on to * The canonical representation is typically used when data is passed on to
* other code components. In many use cases, the TypedData object is mostly * other code components. In many use cases, the TypedData object is mostly
* unified adapter wrapping a primary value (e.g. a string, an entity...) * unified adapter wrapping a primary value (a string, an entity, etc.) which
* which is the canonical representation that consuming code like constraint * is the canonical representation that consuming code like constraint
* validators are really interested in. For some APIs, though, the domain * validators are really interested in. For some APIs, though, the domain
* object (e.g. Field API's FieldItem and FieldItemList) directly implements * object (for example, Field API's FieldItem and FieldItemList) directly
* TypedDataInterface, and the canonical representation is thus the data * implements TypedDataInterface, and the canonical representation is thus the
* object itself. * data object itself.
* *
* When a TypedData object gets validated, for example, its canonical * When a TypedData object gets validated, for example, its canonical
* representation is passed on to constraint validators, which thus receive * representation is passed on to constraint validators, which thus receive

4
core/lib/Drupal/Core/Validation/ConstraintManager.php
View File

@ -22,8 +22,8 @@ use Drupal\Core\StringTranslation\TranslatableMarkup;
* plugin configuration during plugin instantiation. * plugin configuration during plugin instantiation.
* *
* While core does not prefix constraint plugins, modules have to prefix them * While core does not prefix constraint plugins, modules have to prefix them
* with the module name in order to avoid any naming conflicts. E.g. a "profile" * with the module name in order to avoid any naming conflicts; for example, a
* module would have to prefix any constraints with "Profile". * "profile" module would have to prefix any constraints with "Profile".
* *
* Constraint plugins may specify data types to which support is limited via the * Constraint plugins may specify data types to which support is limited via the
* 'type' key of plugin definitions. See * 'type' key of plugin definitions. See

4
core/lib/Drupal/Core/Validation/Plugin/Validation/Constraint/AllowedValuesConstraintValidator.php
View File

@ -68,8 +68,8 @@ class AllowedValuesConstraintValidator extends ChoiceValidator implements Contai
// The parent implementation ignores values that are not set, but makes // The parent implementation ignores values that are not set, but makes
// sure some choices are available firstly. However, we want to support // sure some choices are available firstly. However, we want to support
// empty choices for undefined values, e.g. if a term reference field // empty choices for undefined values; for instance, if a term reference
// points to an empty vocabulary. // field points to an empty vocabulary.
if (!isset($value)) { if (!isset($value)) {
return; return;
} }

3
core/modules/block/block.api.php
View File

@ -190,7 +190,8 @@ function hook_block_build_BASE_BLOCK_ID_alter(array &$build, \Drupal\Core\Block\
* @param \Drupal\block\Entity\Block $block * @param \Drupal\block\Entity\Block $block
* The block instance. * The block instance.
* @param string $operation * @param string $operation
* The operation to be performed, e.g., 'view', 'create', 'delete', 'update'. * The operation to be performed; for instance, 'view', 'create', 'delete', or
* 'update'.
* @param \Drupal\Core\Session\AccountInterface $account * @param \Drupal\Core\Session\AccountInterface $account
* The user object to perform the access check operation on. * The user object to perform the access check operation on.
* *

21
core/modules/block/src/BlockViewBuilder.php
View File

@ -211,14 +211,15 @@ class BlockViewBuilder extends EntityViewBuilder {
if ($content !== NULL && !Element::isEmpty($content)) { if ($content !== NULL && !Element::isEmpty($content)) {
// Place the $content returned by the block plugin into a 'content' child // Place the $content returned by the block plugin into a 'content' child
// element, as a way to allow the plugin to have complete control of its // element, as a way to allow the plugin to have complete control of its
// properties and rendering (e.g., its own #theme) without conflicting // properties and rendering (for instance, its own #theme) without
// with the properties used above, or alternate ones used by alternate // conflicting with the properties used above, or alternate ones used by
// block rendering approaches in contrib (e.g., Panels). However, the use // alternate block rendering approaches in contrib (for instance, Panels).
// of a child element is an implementation detail of this particular block // However, the use of a child element is an implementation detail of this
// rendering approach. Semantically, the content returned by the plugin // particular block rendering approach. Semantically, the content returned
// "is the" block, and in particular, #attributes and #contextual_links is // by the plugin "is the" block, and in particular, #attributes and
// information about the *entire* block. Therefore, we must move these // #contextual_links is information about the *entire* block. Therefore,
// properties from $content and merge them into the top-level element. // we must move these properties from $content and merge them into the
// top-level element.
foreach (array('#attributes', '#contextual_links') as $property) { foreach (array('#attributes', '#contextual_links') as $property) {
if (isset($content[$property])) { if (isset($content[$property])) {
$build[$property] += $content[$property]; $build[$property] += $content[$property];
@ -232,8 +233,8 @@ class BlockViewBuilder extends EntityViewBuilder {
else { else {
// Abort rendering: render as the empty string and ensure this block is // Abort rendering: render as the empty string and ensure this block is
// render cached, so we can avoid the work of having to repeatedly // render cached, so we can avoid the work of having to repeatedly
// determine whether the block is empty. E.g. modifying or adding entities // determine whether the block is empty. For instance, modifying or adding
// could cause the block to no longer be empty. // entities could cause the block to no longer be empty.
$build = array( $build = array(
'#markup' => '', '#markup' => '',
'#cache' => $build['#cache'], '#cache' => $build['#cache'],

6
core/modules/book/src/BookExport.php
View File

@ -58,9 +58,9 @@ class BookExport {
* The given node is embedded to its absolute depth in a top level section. For * The given node is embedded to its absolute depth in a top level section. For
* example, a child node with depth 2 in the hierarchy is contained in * example, a child node with depth 2 in the hierarchy is contained in
* (otherwise empty) <div> elements corresponding to depth 0 and depth 1. * (otherwise empty) <div> elements corresponding to depth 0 and depth 1.
* This is intended to support WYSIWYG output - e.g., level 3 sections always * This is intended to support WYSIWYG output; for instance, level 3 sections
* look like level 3 sections, no matter their depth relative to the node * always look like level 3 sections, no matter their depth relative to the
* selected to be exported as printer-friendly HTML. * node selected to be exported as printer-friendly HTML.
* *
* @param \Drupal\node\NodeInterface $node * @param \Drupal\node\NodeInterface $node
* The node to export. * The node to export.

7
core/modules/ckeditor/src/CKEditorPluginContextualInterface.php
View File

@ -16,9 +16,10 @@ use Drupal\editor\Entity\Editor;
* or enable themselves based on the configuration of another setting, such as * or enable themselves based on the configuration of another setting, such as
* enabling based on a particular button being present in the toolbar. * enabling based on a particular button being present in the toolbar.
* *
* If a contextually enabled CKEditor plugin must also be configurable (e.g. in * If a contextually enabled CKEditor plugin must also be configurable (for
* the case where it must be enabled based on an explicit setting), then one * instance, in the case where it must be enabled based on an explicit setting),
* must also implement the CKEditorPluginConfigurableInterface interface. * then one must also implement the CKEditorPluginConfigurableInterface
* interface.
* *
* @see \Drupal\ckeditor\CKEditorPluginInterface * @see \Drupal\ckeditor\CKEditorPluginInterface
* @see \Drupal\ckeditor\CKEditorPluginButtonsInterface * @see \Drupal\ckeditor\CKEditorPluginButtonsInterface

10
core/modules/ckeditor/src/Plugin/CKEditorPlugin/Internal.php
View File

@ -477,11 +477,11 @@ class Internal extends CKEditorPluginBase implements ContainerFactoryPluginInter
// Once validated, an element or its property cannot be // Once validated, an element or its property cannot be
// invalidated by another rule. // invalidated by another rule.
// That means that the most permissive setting wins. Which means that // That means that the most permissive setting wins. Which means that
// it will still be allowed by CKEditor to e.g. define any style, no // it will still be allowed by CKEditor, for instance, to define any
// matter what the "*" tag's restrictions may be. If there's a setting // style, no matter what the "*" tag's restrictions may be. If there
// for either the "style" or "class" attribute, it cannot possibly be // is a setting for either the "style" or "class" attribute, it cannot
// more permissive than what was set above. Hence: inherit from the // possibly be more permissive than what was set above. Hence, inherit
// "*" tag where possible. // from the "*" tag where possible.
if (isset($html_restrictions['allowed']['*'])) { if (isset($html_restrictions['allowed']['*'])) {
$wildcard = $html_restrictions['allowed']['*']; $wildcard = $html_restrictions['allowed']['*'];
if (isset($wildcard['style'])) { if (isset($wildcard['style'])) {

11
core/modules/ckeditor/src/Plugin/Editor/CKEditor.php
View File

@ -187,8 +187,8 @@ class CKEditor extends EditorBase implements ContainerFactoryPluginInterface {
// Hidden CKEditor instance. We need a hidden CKEditor instance with all // Hidden CKEditor instance. We need a hidden CKEditor instance with all
// plugins enabled, so we can retrieve CKEditor's per-feature metadata (on // plugins enabled, so we can retrieve CKEditor's per-feature metadata (on
// which tags, attributes, styles and classes are enabled). This metadata is // which tags, attributes, styles and classes are enabled). This metadata is
// necessary for certain filters' (e.g. the html_filter filter) settings to // necessary for certain filters' (for instance, the html_filter filter)
// be updated accordingly. // settings to be updated accordingly.
// Get a list of all external plugins and their corresponding files. // Get a list of all external plugins and their corresponding files.
$plugins = array_keys($this->ckeditorPluginManager->getDefinitions()); $plugins = array_keys($this->ckeditorPluginManager->getDefinitions());
$all_external_plugins = array(); $all_external_plugins = array();
@ -348,9 +348,10 @@ class CKEditor extends EditorBase implements ContainerFactoryPluginInterface {
// If this language code is available in a Drupal mapping, use that to // If this language code is available in a Drupal mapping, use that to
// compute a possibility for matching from the Drupal langcode to the // compute a possibility for matching from the Drupal langcode to the
// CKEditor langcode. // CKEditor langcode.
// e.g. CKEditor uses the langcode 'no' for Norwegian, Drupal uses 'nb'. // For instance, CKEditor uses the langcode 'no' for Norwegian, Drupal
// This would then remove the 'no' => 'no' mapping and replace it with // uses 'nb'. This would then remove the 'no' => 'no' mapping and replace
// 'nb' => 'no'. Now Drupal knows which CKEditor translation to load. // it with 'nb' => 'no'. Now Drupal knows which CKEditor translation to
// load.
if (isset($language_mappings[$langcode]) && !isset($langcodes[$language_mappings[$langcode]])) { if (isset($language_mappings[$langcode]) && !isset($langcodes[$language_mappings[$langcode]])) {
$langcodes[$language_mappings[$langcode]] = $langcode; $langcodes[$language_mappings[$langcode]] = $langcode;
unset($langcodes[$langcode]); unset($langcodes[$langcode]);

10
core/modules/comment/comment.module
View File

@ -245,7 +245,8 @@ function comment_node_view_alter(array &$build, EntityInterface $node, EntityVie
* @param \Drupal\comment\CommentInterface $comment * @param \Drupal\comment\CommentInterface $comment
* The comment object. * The comment object.
* @param $view_mode * @param $view_mode
* (optional) View mode; e.g., 'full', 'teaser', etc. Defaults to 'full'. * (optional) View mode; for instance, 'full', 'teaser', etc. Defaults to
* 'full'.
* @param $langcode * @param $langcode
* (optional) A language code to use for rendering. Defaults to the global * (optional) A language code to use for rendering. Defaults to the global
* content language of the current request. * content language of the current request.
@ -266,7 +267,8 @@ function comment_view(CommentInterface $comment, $view_mode = 'full', $langcode
* @param $comments * @param $comments
* An array of comments as returned by entity_load_multiple(). * An array of comments as returned by entity_load_multiple().
* @param $view_mode * @param $view_mode
* View mode; e.g., 'full', 'teaser', etc. * (optional) View mode; for instance, 'full', 'teaser', etc. Defaults to
* 'full'.
* @param $langcode * @param $langcode
* (optional) A string indicating the language field values are to be shown * (optional) A string indicating the language field values are to be shown
* in. If no language is provided the current content language is used. * in. If no language is provided the current content language is used.
@ -641,8 +643,8 @@ function template_preprocess_comment(&$variables) {
} }
if (theme_get_setting('features.comment_user_picture')) { if (theme_get_setting('features.comment_user_picture')) {
// To change user picture settings (e.g., image style), edit the 'compact' // To change user picture settings (for instance, image style), edit the
// view mode on the User entity. // 'compact' view mode on the User entity.
$variables['user_picture'] = user_view($account, 'compact'); $variables['user_picture'] = user_view($account, 'compact');
} }
else { else {

2
core/modules/comment/templates/comment.html.twig
View File

@ -27,7 +27,7 @@
* - title: Comment title, linked to the comment. * - title: Comment title, linked to the comment.
* - attributes: HTML attributes for the containing element. * - attributes: HTML attributes for the containing element.
* The attributes.class may contain one or more of the following classes: * The attributes.class may contain one or more of the following classes:
* - comment: The current template type; e.g., 'theming hook'. * - comment: The current template type; for instance, 'theming hook'.
* - by-anonymous: Comment by an unregistered user. * - by-anonymous: Comment by an unregistered user.
* - by-{entity-type}-author: Comment by the author of the parent entity, * - by-{entity-type}-author: Comment by the author of the parent entity,
* eg. by-node-author. * eg. by-node-author.

15
core/modules/config_translation/src/ConfigMapperManager.php
View File

@ -87,13 +87,14 @@ class ConfigMapperManager extends DefaultPluginManager implements ConfigMapperMa
if (!isset($this->discovery)) { if (!isset($this->discovery)) {
// Look at all themes and modules. // Look at all themes and modules.
// @todo If the list of installed modules and themes is changed, new // @todo If the list of installed modules and themes is changed, new
// definitions are not picked up immediately and obsolete definitions are // definitions are not picked up immediately and obsolete definitions
// not removed, because the list of search directories is only compiled // are not removed, because the list of search directories is only
// once in this constructor. The current code only works due to // compiled once in this constructor. The current code only works due to
// coincidence: The request that installs e.g. a new theme does not // coincidence: The request that installs (for instance, a new theme)
// instantiate this plugin manager at the beginning of the request; when // does not instantiate this plugin manager at the beginning of the
// routes are being rebuilt at the end of the request, this service only // request; when routes are being rebuilt at the end of the request,
// happens to get instantiated with the updated list of installed themes. // this service only happens to get instantiated with the updated list
// of installed themes.
$directories = array(); $directories = array();
foreach ($this->moduleHandler->getModuleList() as $name => $module) { foreach ($this->moduleHandler->getModuleList() as $name => $module) {
$directories[$name] = $module->getPath(); $directories[$name] = $module->getPath();

6
core/modules/content_translation/content_translation.module
View File

@ -96,9 +96,9 @@ function content_translation_language_types_info_alter(array &$language_types) {
* canonical link template cannot be enabled for translation. Setting this key * canonical link template cannot be enabled for translation. Setting this key
* to TRUE overrides that. When that key is set, the Content Translation * to TRUE overrides that. When that key is set, the Content Translation
* module will not provide any UI for translating the entity type, and the * module will not provide any UI for translating the entity type, and the
* entity type should implement its own UI. This is useful for (e.g.) entity * entity type should implement its own UI. For instance, this is useful for
* types that are embedded into others for editing (which would not need a * entity types that are embedded into others for editing (which would not
* canonical link, but could still support translation). * need a canonical link, but could still support translation).
* - content_translation_metadata: To implement its business logic the content * - content_translation_metadata: To implement its business logic the content
* translation UI relies on various metadata items describing the translation * translation UI relies on various metadata items describing the translation
* state. The default implementation is provided by * state. The default implementation is provided by

6
core/modules/content_translation/src/ContentTranslationHandler.php
View File

@ -177,8 +177,8 @@ class ContentTranslationHandler implements ContentTranslationHandlerInterface, E
protected function hasAuthor() { protected function hasAuthor() {
// Check for field named uid, but only in case the entity implements the // Check for field named uid, but only in case the entity implements the
// EntityOwnerInterface. This helps to exclude cases, where the uid is // EntityOwnerInterface. This helps to exclude cases, where the uid is
// defined as field name, but is not meant to be an owner field e.g. the // defined as field name, but is not meant to be an owner field; for
// User entity. // instance, the User entity.
return $this->entityType->isSubclassOf('\Drupal\user\EntityOwnerInterface') && $this->checkFieldStorageDefinitionTranslatability('uid'); return $this->entityType->isSubclassOf('\Drupal\user\EntityOwnerInterface') && $this->checkFieldStorageDefinitionTranslatability('uid');
} }
@ -550,7 +550,7 @@ class ContentTranslationHandler implements ContentTranslationHandlerInterface, E
// Update #title attribute for all elements that are allowed to have a // Update #title attribute for all elements that are allowed to have a
// #title attribute according to the Form API Reference. The reason for this // #title attribute according to the Form API Reference. The reason for this
// check is because some elements have a #title attribute even though it is // check is because some elements have a #title attribute even though it is
// not rendered, e.g. field containers. // not rendered; for instance, field containers.
if (isset($element['#type']) && isset($fapi_title_elements[$element['#type']]) && isset($element['#title'])) { if (isset($element['#type']) && isset($fapi_title_elements[$element['#type']]) && isset($element['#title'])) {
$element['#title'] .= $suffix; $element['#title'] .= $suffix;
} }

8
core/modules/file/src/Tests/FileManagedTestBase.php
View File

@ -33,9 +33,9 @@ abstract class FileManagedTestBase extends WebTestBase {
* Assert that all of the specified hook_file_* hooks were called once, other * Assert that all of the specified hook_file_* hooks were called once, other
* values result in failure. * values result in failure.
* *
* @param array $expected * @param string[] $expected
* Array with string containing with the hook name, e.g. 'load', 'save', * An array of strings containing with the hook name; for example, 'load',
* 'insert', etc. * 'save', 'insert', etc.
*/ */
function assertFileHooksCalled($expected) { function assertFileHooksCalled($expected) {
\Drupal::state()->resetCache(); \Drupal::state()->resetCache();
@ -66,7 +66,7 @@ abstract class FileManagedTestBase extends WebTestBase {
* Assert that a hook_file_* hook was called a certain number of times. * Assert that a hook_file_* hook was called a certain number of times.
* *
* @param string $hook * @param string $hook
* String with the hook name, e.g. 'load', 'save', 'insert', etc. * String with the hook name; for instance, 'load', 'save', 'insert', etc.
* @param int $expected_count * @param int $expected_count
* Optional integer count. * Optional integer count.
* @param string|NULL $message * @param string|NULL $message