From aaabb05c3d9a00b0e5317f802b5ec6ba99da1a1e Mon Sep 17 00:00:00 2001
From: Jennifer Hodgdon <yahgrp@poplarware.com>
Date: Thu, 3 Dec 2015 11:04:31 -0800
Subject: [PATCH] Issue #2627018 by Lars Toomre: Some fixes for 'e.g.' in
docblocks and code comments
---
core/CHANGELOG.txt | 6 +-
core/includes/database.inc | 80 ++++++++++---------
core/lib/Drupal.php | 12 +--
.../Drupal/Component/Utility/UrlHelper.php | 24 +++---
.../AuthenticationProviderFilterInterface.php | 5 +-
.../Core/Cache/CacheableResponseInterface.php | 6 +-
.../Cache/Context/CacheContextsManager.php | 16 ++--
.../Entity/ConfigEntityStorageInterface.php | 4 +-
.../lib/Drupal/Core/Config/InstallStorage.php | 6 +-
...lyRenderingControllerWrapperSubscriber.php | 4 +-
core/lib/Drupal/Core/Image/ImageInterface.php | 27 ++++---
.../lib/Drupal/Core/Mail/MailFormatHelper.php | 4 +-
.../Core/Plugin/Context/ContextInterface.php | 6 +-
.../Discovery/AnnotatedClassDiscovery.php | 6 +-
.../Core/Plugin/Discovery/YamlDiscovery.php | 4 +-
.../Discovery/YamlDiscoveryDecorator.php | 4 +-
.../Drupal/Core/Render/RendererInterface.php | 22 ++---
.../StreamWrapper/StreamWrapperInterface.php | 6 +-
.../Drupal/Core/Template/TwigExtension.php | 4 +-
.../TypedData/TypedDataManagerInterface.php | 22 ++---
.../Core/Validation/ConstraintManager.php | 4 +-
.../AllowedValuesConstraintValidator.php | 4 +-
core/modules/block/block.api.php | 3 +-
core/modules/block/src/BlockViewBuilder.php | 21 ++---
core/modules/book/src/BookExport.php | 6 +-
.../src/CKEditorPluginContextualInterface.php | 7 +-
.../src/Plugin/CKEditorPlugin/Internal.php | 10 +--
.../ckeditor/src/Plugin/Editor/CKEditor.php | 11 +--
core/modules/comment/comment.module | 10 ++-
.../comment/templates/comment.html.twig | 2 +-
.../src/ConfigMapperManager.php | 15 ++--
.../content_translation.module | 6 +-
.../src/ContentTranslationHandler.php | 6 +-
.../file/src/Tests/FileManagedTestBase.php | 8 +-
34 files changed, 204 insertions(+), 177 deletions(-)
diff --git a/core/CHANGELOG.txt b/core/CHANGELOG.txt
index 6b8e812d52e8..01a3dd484c16 100644
--- a/core/CHANGELOG.txt
+++ b/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.
diff --git a/core/includes/database.inc b/core/includes/database.inc
index 477e8437a01f..ff03885a25c4 100644
--- a/core/includes/database.inc
+++ b/core/includes/database.inc
@@ -32,8 +32,8 @@
* 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
- * should be named with a trailing bracket like :example[]
+ * an array of values to be expanded (for example, with an IN query), the
+ * 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 @@
*
* @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()
diff --git a/core/lib/Drupal.php b/core/lib/Drupal.php
index ad525dd8578d..4020f7cb7570 100644
--- a/core/lib/Drupal.php
+++ b/core/lib/Drupal.php
@@ -423,11 +423,11 @@ public static function httpClient() {
* 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
- * enough. Optional, defaults to AND.
+ * (optional) Either 'AND' if all conditions in the query need to apply, or
+ * '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 @@ public static function entityQuery($entity_type, $conjunction = 'AND') {
* 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
- * enough. Optional, defaults to AND.
+ * (optional) Either 'AND' if all conditions in the query need to apply, or
+ * '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.
diff --git a/core/lib/Drupal/Component/Utility/UrlHelper.php b/core/lib/Drupal/Component/Utility/UrlHelper.php
index 1763c23611c3..9166b34a5edf 100644
--- a/core/lib/Drupal/Component/Utility/UrlHelper.php
+++ b/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,
- * e.g. \Drupal::request()->query->all().
+ * The query parameter array to be processed; for instance,
+ * \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 @@ public static function parse($url) {
}
// Internal URLs.
else {
- // parse_url() does not support relative URLs, so make it absolute. E.g. the
- // relative URL "foo/bar:1" isn't properly parsed.
+ // parse_url() does not support relative URLs, so make it absolute. For
+ // 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 @@ public static function encodePath($path) {
}
/**
- * 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
- * treat it as potentially insecure.
+ * An example of an external path is http://example.com. If a path cannot be
+ * 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 @@ public static function setAllowedProtocols(array $protocols = array()) {
}
/**
- * 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 @@ public static function setAllowedProtocols(array $protocols = array()) {
* 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
- * HTML validation). This can be avoided by using
+ * produce valid HTML (for example, malformed URLs within "href" attributes
+ * 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.
*
diff --git a/core/lib/Drupal/Core/Authentication/AuthenticationProviderFilterInterface.php b/core/lib/Drupal/Core/Authentication/AuthenticationProviderFilterInterface.php
index 99f8e105090e..002d5204bc92 100644
--- a/core/lib/Drupal/Core/Authentication/AuthenticationProviderFilterInterface.php
+++ b/core/lib/Drupal/Core/Authentication/AuthenticationProviderFilterInterface.php
@@ -13,8 +13,9 @@
* 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
- * auth or an URL token authentication method to API-only routes.
+ * For instance, there are good reasons to restrict insecure methods like HTTP
+ * basic authentication or an URL token authentication method to API-only
+ * routes.
*/
interface AuthenticationProviderFilterInterface {
diff --git a/core/lib/Drupal/Core/Cache/CacheableResponseInterface.php b/core/lib/Drupal/Core/Cache/CacheableResponseInterface.php
index 0bca8d1fcff1..c43085e1feea 100644
--- a/core/lib/Drupal/Core/Cache/CacheableResponseInterface.php
+++ b/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
- * result, we must make sure their cacheability metadata is present on the
- * response. This method makes doing that simple.
+ * For instance, when a response depends on some configuration, an entity, or
+ * an access result, we must make sure their cacheability metadata is present
+ * on the response. This method makes doing that simple.
*
* @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $dependency
* The dependency. If the object implements CacheableDependencyInterface,
diff --git a/core/lib/Drupal/Core/Cache/Context/CacheContextsManager.php b/core/lib/Drupal/Core/Cache/Context/CacheContextsManager.php
index 81d67350aa9b..c8752716cb07 100644
--- a/core/lib/Drupal/Core/Cache/Context/CacheContextsManager.php
+++ b/core/lib/Drupal/Core/Cache/Context/CacheContextsManager.php
@@ -92,9 +92,10 @@ public function getLabels($include_calculated_cache_contexts = FALSE) {
*
* 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'
- * - a calculated cache context ID, followed by a double colon, followed by
- * the parameter for the calculated cache context, e.g. 'bar:some_parameter'
+ * is a cache context ID); for example, 'foo'.
+ * - a calculated cache context ID, followed by a colon, followed by
+ * 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 @@ public function convertTokensToKeys(array $context_tokens) {
* 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')
- * is meaningless because "per role" is implied by "per user".
+ * For example, when caching per user ('user'), also caching per role
+ * ('user.roles') is meaningless because "per role" is implied by "per user".
*
- * Examples — remember that the period indicates hierarchy and the colon can
- * be used to get a specific value of a calculated cache context:
+ * In the following examples, remember that the period indicates hierarchy and
+ * 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']
diff --git a/core/lib/Drupal/Core/Config/Entity/ConfigEntityStorageInterface.php b/core/lib/Drupal/Core/Config/Entity/ConfigEntityStorageInterface.php
index 55c119323b74..10b8142be662 100644
--- a/core/lib/Drupal/Core/Config/Entity/ConfigEntityStorageInterface.php
+++ b/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.
diff --git a/core/lib/Drupal/Core/Config/InstallStorage.php b/core/lib/Drupal/Core/Config/InstallStorage.php
index a1d967d06505..ca96bd77af47 100644
--- a/core/lib/Drupal/Core/Config/InstallStorage.php
+++ b/core/lib/Drupal/Core/Config/InstallStorage.php
@@ -80,9 +80,9 @@ public function __construct($directory = self::CONFIG_INSTALL_DIRECTORY, $collec
* 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
- * in the profile first (whereas the profile is never the owner), only
- * afterwards check for a corresponding module or theme.
+ * installation profiles. For instance, a config object actually has to be
+ * searched in the profile first (whereas the profile is never the owner);
+ * only afterwards check for a corresponding module or theme.
*/
public function getFilePath($name) {
$folders = $this->getAllFolders();
diff --git a/core/lib/Drupal/Core/EventSubscriber/EarlyRenderingControllerWrapperSubscriber.php b/core/lib/Drupal/Core/EventSubscriber/EarlyRenderingControllerWrapperSubscriber.php
index da6327d55287..0daf17675950 100644
--- a/core/lib/Drupal/Core/EventSubscriber/EarlyRenderingControllerWrapperSubscriber.php
+++ b/core/lib/Drupal/Core/EventSubscriber/EarlyRenderingControllerWrapperSubscriber.php
@@ -160,8 +160,8 @@ protected function wrapControllerExecutionInRenderContext($controller, array $ar
}
else {
// A Response or domain object is returned that does not care about
- // attachments nor cacheability. E.g. a RedirectResponse. It is safe to
- // discard any early rendering metadata.
+ // attachments nor cacheability; for instance, a RedirectResponse. It is
+ // safe to discard any early rendering metadata.
}
}
diff --git a/core/lib/Drupal/Core/Image/ImageInterface.php b/core/lib/Drupal/Core/Image/ImageInterface.php
index da8496b2004e..2c953f53a2f9 100644
--- a/core/lib/Drupal/Core/Image/ImageInterface.php
+++ b/core/lib/Drupal/Core/Image/ImageInterface.php
@@ -86,9 +86,12 @@ public function getToolkitId();
* @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
- * operation, e.g. array('width' => 50, 'height' => 100,
- * 'upscale' => TRUE).
+ * (optional) An associative array of arguments to be passed to the toolkit
+ * operation; for instance,
+ * @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 @@ public function save($destination = NULL);
* @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.).
- * Allowed values depend on the implementation of the image toolkit.
+ * (optional) The extension of the image file (for instance, 'png', 'gif',
+ * 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 @@ public function scaleAndCrop($width, $height);
* extension.
*
* @param string $extension
- * The extension to convert to (e.g. 'jpeg' or 'png'). Allowed values depend
- * on the current image toolkit.
+ * The extension to convert to (for instance, 'jpeg' or 'png'). Allowed
+ * values depend on the current image toolkit.
*
* @return bool
* TRUE on success, FALSE on failure.
@@ -231,10 +234,10 @@ public function desaturate();
* 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
- * black, 0xff00ff for magenta, and 0xffffff for white. For images that
- * support transparency, this will default to transparent. Otherwise it will
- * be white.
+ * for the uncovered area of the image after the rotation; for example,
+ * 0x000000 for black, 0xff00ff for magenta, and 0xffffff for white. When
+ * NULL (the default) is specified, for images that support transparency,
+ * this will default to transparent; otherwise, it will default to white.
*
* @return bool
* TRUE on success, FALSE on failure.
diff --git a/core/lib/Drupal/Core/Mail/MailFormatHelper.php b/core/lib/Drupal/Core/Mail/MailFormatHelper.php
index 86e85531a284..6ea977f4a81b 100644
--- a/core/lib/Drupal/Core/Mail/MailFormatHelper.php
+++ b/core/lib/Drupal/Core/Mail/MailFormatHelper.php
@@ -297,8 +297,8 @@ public static function htmlToText($string, $allowed_tags = NULL) {
* 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
- * hello_drupal.docx will produce the following Content-Type:
+ * and wrapping that line will break the email format. For instance, the
+ * attached file hello_drupal.docx will produce the following Content-Type:
* @code
* Content-Type:
* application/vnd.openxmlformats-officedocument.wordprocessingml.document;
diff --git a/core/lib/Drupal/Core/Plugin/Context/ContextInterface.php b/core/lib/Drupal/Core/Plugin/Context/ContextInterface.php
index 067e76a467c7..5cda9be05c3d 100644
--- a/core/lib/Drupal/Core/Plugin/Context/ContextInterface.php
+++ b/core/lib/Drupal/Core/Plugin/Context/ContextInterface.php
@@ -32,9 +32,9 @@ public function getContextData();
/**
* Adds a dependency on an object: merges its cacheability metadata.
*
- * E.g. when a context depends on some configuration, an entity, or an access
- * result, we must make sure their cacheability metadata is present on the
- * response. This method makes doing that simple.
+ * For example, when a context depends on some configuration, an entity, or an
+ * access result, we must make sure their cacheability metadata is present on
+ * the response. This method makes doing that simple.
*
* @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $dependency
* The dependency. If the object implements CacheableDependencyInterface,
diff --git a/core/lib/Drupal/Core/Plugin/Discovery/AnnotatedClassDiscovery.php b/core/lib/Drupal/Core/Plugin/Discovery/AnnotatedClassDiscovery.php
index 6bc3bbbf6831..8cb4888d7d6c 100644
--- a/core/lib/Drupal/Core/Plugin/Discovery/AnnotatedClassDiscovery.php
+++ b/core/lib/Drupal/Core/Plugin/Discovery/AnnotatedClassDiscovery.php
@@ -120,13 +120,13 @@ protected function getPluginNamespaces() {
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.
- // E.g. DRUPAL_ROOT . '/core/modules/views/src' may become
+ // the directory where plugins are found. For example,
+ // DRUPAL_ROOT . '/core/modules/views/src' may become
// DRUPAL_ROOT . '/core/modules/views/src/Plugin/Block'.
$plugin_namespaces[$namespace][] = $dir . $this->directorySuffix;
}
diff --git a/core/lib/Drupal/Core/Plugin/Discovery/YamlDiscovery.php b/core/lib/Drupal/Core/Plugin/Discovery/YamlDiscovery.php
index 97ea37460b26..058c752c88d1 100644
--- a/core/lib/Drupal/Core/Plugin/Discovery/YamlDiscovery.php
+++ b/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
- * 'MODULE.test.yml'.
+ * The file name suffix to use for discovery; for example, 'test' will
+ * become 'MODULE.test.yml'.
* @param array $directories
* An array of directories to scan.
*/
diff --git a/core/lib/Drupal/Core/Plugin/Discovery/YamlDiscoveryDecorator.php b/core/lib/Drupal/Core/Plugin/Discovery/YamlDiscoveryDecorator.php
index 2957dc04c04f..332e740a47d8 100644
--- a/core/lib/Drupal/Core/Plugin/Discovery/YamlDiscoveryDecorator.php
+++ b/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
- * 'MODULE.test.yml'.
+ * The file name suffix to use for discovery; for instance, 'test' will
+ * become 'MODULE.test.yml'.
* @param array $directories
* An array of directories to scan.
*/
diff --git a/core/lib/Drupal/Core/Render/RendererInterface.php b/core/lib/Drupal/Core/Render/RendererInterface.php
index 3cd1ff063827..48cece4453fe 100644
--- a/core/lib/Drupal/Core/Render/RendererInterface.php
+++ b/core/lib/Drupal/Core/Render/RendererInterface.php
@@ -42,9 +42,9 @@ public function renderRoot(&$elements);
*
* Calls ::render() in such a way that placeholders are replaced.
*
- * Useful for e.g. rendering the values of tokens or emails, which need a
- * render array being turned into a string, but don't need any of the
- * bubbleable metadata (the attached assets the cache tags).
+ * Useful for instance when rendering the values of tokens or emails, which
+ * need a render array being turned into a string, but do not need any of the
+ * 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 @@ public function renderPlaceholder($placeholder, array $elements);
* - '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
- * mapped to the current user's ID.)
+ * converted to a final value depending on the request. (For instance,
+ * '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 @@ public function renderPlaceholder($placeholder, array $elements);
* 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
- * pushed onto the stack element at the beginning of rendering this
+ * So if for instance this element was a child element, then a new frame
+ * 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 @@ public function mergeBubbleableMetadata(array $a, array $b);
/**
* Adds a dependency on an object: merges its cacheability metadata.
*
- * E.g. when a render array depends on some configuration, an entity, or an
- * access result, we must make sure their cacheability metadata is present on
- * the render array. This method makes doing that simple.
+ * For instance, when a render array depends on some configuration, an entity,
+ * or an access result, we must make sure their cacheability metadata is
+ * present on the render array. This method makes doing that simple.
*
* @param array &$elements
* The render array to update.
diff --git a/core/lib/Drupal/Core/StreamWrapper/StreamWrapperInterface.php b/core/lib/Drupal/Core/StreamWrapper/StreamWrapperInterface.php
index 34dc3331fa2c..f13cfb80fc9c 100644
--- a/core/lib/Drupal/Core/StreamWrapper/StreamWrapperInterface.php
+++ b/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.
- * E.g. the temporary directory for uploads.
+ * Defines the stream wrapper bit flag for a hidden file.
+ *
+ * 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;
diff --git a/core/lib/Drupal/Core/Template/TwigExtension.php b/core/lib/Drupal/Core/Template/TwigExtension.php
index d0d6e65457f2..69f329805120 100644
--- a/core/lib/Drupal/Core/Template/TwigExtension.php
+++ b/core/lib/Drupal/Core/Template/TwigExtension.php
@@ -315,8 +315,8 @@ public function getActiveThemePath() {
* 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
- * be escaped:
+ * constant parameter given. For instance, we know beforehand this will not
+ * need to be escaped:
* - path('route')
* - path('route', {'param': 'value'})
* But the following may need to be escaped:
diff --git a/core/lib/Drupal/Core/TypedData/TypedDataManagerInterface.php b/core/lib/Drupal/Core/TypedData/TypedDataManagerInterface.php
index 3a0220161032..5857b9d3bfa0 100644
--- a/core/lib/Drupal/Core/TypedData/TypedDataManagerInterface.php
+++ b/core/lib/Drupal/Core/TypedData/TypedDataManagerInterface.php
@@ -78,7 +78,7 @@ public function create(DataDefinitionInterface $definition, $value = NULL, $name
* class used by a data type is known, this method allows the creation of data
* 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':
* @code
* $map_definition = \Drupal\Core\TypedData\MapDataDefinition::create();
@@ -137,9 +137,10 @@ public function getInstance(array $options);
* 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
- * 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
* instantiated very often.
+ *
* 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
* and inheriting from the same data type are prototyped.
@@ -203,9 +204,10 @@ public function setValidationConstraintManager(ConstraintManager $constraintMana
* Gets default constraints for the given 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.
- * Besides that any constraints defined for the data type, i.e. below the
- * 'constraint' key of the type's plugin definition, are taken into account.
+ * for example, a NotNull constraint is generated if the data is defined as
+ * required. Besides that, any constraints defined for the data type (that is,
+ * below the 'constraint' key of the type's plugin definition) are taken into
+ * account.
*
* @param \Drupal\Core\TypedData\DataDefinitionInterface $definition
* A data definition.
@@ -222,12 +224,12 @@ public function getDefaultConstraints(DataDefinitionInterface $definition);
*
* The canonical representation is typically used when data is passed on to
* other code components. In many use cases, the TypedData object is mostly
- * unified adapter wrapping a primary value (e.g. a string, an entity...)
- * which is the canonical representation that consuming code like constraint
+ * unified adapter wrapping a primary value (a string, an entity, etc.) which
+ * is the canonical representation that consuming code like constraint
* validators are really interested in. For some APIs, though, the domain
- * object (e.g. Field API's FieldItem and FieldItemList) directly implements
- * TypedDataInterface, and the canonical representation is thus the data
- * object itself.
+ * object (for example, Field API's FieldItem and FieldItemList) directly
+ * implements TypedDataInterface, and the canonical representation is thus the
+ * data object itself.
*
* When a TypedData object gets validated, for example, its canonical
* representation is passed on to constraint validators, which thus receive
diff --git a/core/lib/Drupal/Core/Validation/ConstraintManager.php b/core/lib/Drupal/Core/Validation/ConstraintManager.php
index 1dd9a031490d..631a3d1a6501 100644
--- a/core/lib/Drupal/Core/Validation/ConstraintManager.php
+++ b/core/lib/Drupal/Core/Validation/ConstraintManager.php
@@ -22,8 +22,8 @@
* plugin configuration during plugin instantiation.
*
* 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"
- * module would have to prefix any constraints with "Profile".
+ * with the module name in order to avoid any naming conflicts; for example, a
+ * "profile" module would have to prefix any constraints with "Profile".
*
* Constraint plugins may specify data types to which support is limited via the
* 'type' key of plugin definitions. See
diff --git a/core/lib/Drupal/Core/Validation/Plugin/Validation/Constraint/AllowedValuesConstraintValidator.php b/core/lib/Drupal/Core/Validation/Plugin/Validation/Constraint/AllowedValuesConstraintValidator.php
index a85fbf206065..e2521664e7da 100644
--- a/core/lib/Drupal/Core/Validation/Plugin/Validation/Constraint/AllowedValuesConstraintValidator.php
+++ b/core/lib/Drupal/Core/Validation/Plugin/Validation/Constraint/AllowedValuesConstraintValidator.php
@@ -68,8 +68,8 @@ public function validate($value, Constraint $constraint) {
// The parent implementation ignores values that are not set, but makes
// sure some choices are available firstly. However, we want to support
- // empty choices for undefined values, e.g. if a term reference field
- // points to an empty vocabulary.
+ // empty choices for undefined values; for instance, if a term reference
+ // field points to an empty vocabulary.
if (!isset($value)) {
return;
}
diff --git a/core/modules/block/block.api.php b/core/modules/block/block.api.php
index 078aac64c570..5a28bad6a71d 100644
--- a/core/modules/block/block.api.php
+++ b/core/modules/block/block.api.php
@@ -190,7 +190,8 @@ function hook_block_build_BASE_BLOCK_ID_alter(array &$build, \Drupal\Core\Block\
* @param \Drupal\block\Entity\Block $block
* The block instance.
* @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
* The user object to perform the access check operation on.
*
diff --git a/core/modules/block/src/BlockViewBuilder.php b/core/modules/block/src/BlockViewBuilder.php
index a7cb441f77da..e7279ceb69e6 100644
--- a/core/modules/block/src/BlockViewBuilder.php
+++ b/core/modules/block/src/BlockViewBuilder.php
@@ -211,14 +211,15 @@ public static function preRender($build) {
if ($content !== NULL && !Element::isEmpty($content)) {
// 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
- // properties and rendering (e.g., its own #theme) without conflicting
- // with the properties used above, or alternate ones used by alternate
- // block rendering approaches in contrib (e.g., Panels). However, the use
- // of a child element is an implementation detail of this particular block
- // rendering approach. Semantically, the content returned by the plugin
- // "is the" block, and in particular, #attributes and #contextual_links is
- // information about the *entire* block. Therefore, we must move these
- // properties from $content and merge them into the top-level element.
+ // properties and rendering (for instance, its own #theme) without
+ // conflicting with the properties used above, or alternate ones used by
+ // alternate block rendering approaches in contrib (for instance, Panels).
+ // However, the use of a child element is an implementation detail of this
+ // particular block rendering approach. Semantically, the content returned
+ // by the plugin "is the" block, and in particular, #attributes and
+ // #contextual_links is information about the *entire* block. Therefore,
+ // we must move these properties from $content and merge them into the
+ // top-level element.
foreach (array('#attributes', '#contextual_links') as $property) {
if (isset($content[$property])) {
$build[$property] += $content[$property];
@@ -232,8 +233,8 @@ public static function preRender($build) {
else {
// Abort rendering: render as the empty string and ensure this block is
// render cached, so we can avoid the work of having to repeatedly
- // determine whether the block is empty. E.g. modifying or adding entities
- // could cause the block to no longer be empty.
+ // determine whether the block is empty. For instance, modifying or adding
+ // entities could cause the block to no longer be empty.
$build = array(
'#markup' => '',
'#cache' => $build['#cache'],
diff --git a/core/modules/book/src/BookExport.php b/core/modules/book/src/BookExport.php
index 8a49368a9c02..420b8c5632ce 100644
--- a/core/modules/book/src/BookExport.php
+++ b/core/modules/book/src/BookExport.php
@@ -58,9 +58,9 @@ public function __construct(EntityManagerInterface $entityManager, BookManagerIn
* 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
* (otherwise empty) <div> elements corresponding to depth 0 and depth 1.
- * This is intended to support WYSIWYG output - e.g., level 3 sections always
- * look like level 3 sections, no matter their depth relative to the node
- * selected to be exported as printer-friendly HTML.
+ * This is intended to support WYSIWYG output; for instance, level 3 sections
+ * always look like level 3 sections, no matter their depth relative to the
+ * node selected to be exported as printer-friendly HTML.
*
* @param \Drupal\node\NodeInterface $node
* The node to export.
diff --git a/core/modules/ckeditor/src/CKEditorPluginContextualInterface.php b/core/modules/ckeditor/src/CKEditorPluginContextualInterface.php
index 8c8d2c95f3c0..5bd397fe4eb1 100644
--- a/core/modules/ckeditor/src/CKEditorPluginContextualInterface.php
+++ b/core/modules/ckeditor/src/CKEditorPluginContextualInterface.php
@@ -16,9 +16,10 @@
* or enable themselves based on the configuration of another setting, such as
* enabling based on a particular button being present in the toolbar.
*
- * If a contextually enabled CKEditor plugin must also be configurable (e.g. in
- * the case where it must be enabled based on an explicit setting), then one
- * must also implement the CKEditorPluginConfigurableInterface interface.
+ * If a contextually enabled CKEditor plugin must also be configurable (for
+ * instance, in the case where it must be enabled based on an explicit setting),
+ * then one must also implement the CKEditorPluginConfigurableInterface
+ * interface.
*
* @see \Drupal\ckeditor\CKEditorPluginInterface
* @see \Drupal\ckeditor\CKEditorPluginButtonsInterface
diff --git a/core/modules/ckeditor/src/Plugin/CKEditorPlugin/Internal.php b/core/modules/ckeditor/src/Plugin/CKEditorPlugin/Internal.php
index d1b317e84b52..2dbb4b1b07ac 100644
--- a/core/modules/ckeditor/src/Plugin/CKEditorPlugin/Internal.php
+++ b/core/modules/ckeditor/src/Plugin/CKEditorPlugin/Internal.php
@@ -477,11 +477,11 @@ protected function generateACFSettings(Editor $editor) {
// Once validated, an element or its property cannot be
// invalidated by another rule.
// 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
- // matter what the "*" tag's restrictions may be. If there's a setting
- // for either the "style" or "class" attribute, it cannot possibly be
- // more permissive than what was set above. Hence: inherit from the
- // "*" tag where possible.
+ // it will still be allowed by CKEditor, for instance, to define any
+ // style, no matter what the "*" tag's restrictions may be. If there
+ // is a setting for either the "style" or "class" attribute, it cannot
+ // possibly be more permissive than what was set above. Hence, inherit
+ // from the "*" tag where possible.
if (isset($html_restrictions['allowed']['*'])) {
$wildcard = $html_restrictions['allowed']['*'];
if (isset($wildcard['style'])) {
diff --git a/core/modules/ckeditor/src/Plugin/Editor/CKEditor.php b/core/modules/ckeditor/src/Plugin/Editor/CKEditor.php
index abf409b6497c..5ae5e85b2105 100644
--- a/core/modules/ckeditor/src/Plugin/Editor/CKEditor.php
+++ b/core/modules/ckeditor/src/Plugin/Editor/CKEditor.php
@@ -187,8 +187,8 @@ public function settingsForm(array $form, FormStateInterface $form_state, Editor
// Hidden CKEditor instance. We need a hidden CKEditor instance with all
// plugins enabled, so we can retrieve CKEditor's per-feature metadata (on
// which tags, attributes, styles and classes are enabled). This metadata is
- // necessary for certain filters' (e.g. the html_filter filter) settings to
- // be updated accordingly.
+ // necessary for certain filters' (for instance, the html_filter filter)
+ // settings to be updated accordingly.
// Get a list of all external plugins and their corresponding files.
$plugins = array_keys($this->ckeditorPluginManager->getDefinitions());
$all_external_plugins = array();
@@ -348,9 +348,10 @@ public function getLangcodes() {
// If this language code is available in a Drupal mapping, use that to
// compute a possibility for matching from the Drupal langcode to the
// CKEditor langcode.
- // e.g. CKEditor uses the langcode 'no' for Norwegian, Drupal uses 'nb'.
- // This would then remove the 'no' => 'no' mapping and replace it with
- // 'nb' => 'no'. Now Drupal knows which CKEditor translation to load.
+ // For instance, CKEditor uses the langcode 'no' for Norwegian, Drupal
+ // uses 'nb'. This would then remove the 'no' => 'no' mapping and replace
+ // it with 'nb' => 'no'. Now Drupal knows which CKEditor translation to
+ // load.
if (isset($language_mappings[$langcode]) && !isset($langcodes[$language_mappings[$langcode]])) {
$langcodes[$language_mappings[$langcode]] = $langcode;
unset($langcodes[$langcode]);
diff --git a/core/modules/comment/comment.module b/core/modules/comment/comment.module
index dbeccb655f2d..e333b565add8 100644
--- a/core/modules/comment/comment.module
+++ b/core/modules/comment/comment.module
@@ -245,7 +245,8 @@ function comment_node_view_alter(array &$build, EntityInterface $node, EntityVie
* @param \Drupal\comment\CommentInterface $comment
* The comment object.
* @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
* (optional) A language code to use for rendering. Defaults to the global
* content language of the current request.
@@ -266,7 +267,8 @@ function comment_view(CommentInterface $comment, $view_mode = 'full', $langcode
* @param $comments
* An array of comments as returned by entity_load_multiple().
* @param $view_mode
- * View mode; e.g., 'full', 'teaser', etc.
+ * (optional) View mode; for instance, 'full', 'teaser', etc. Defaults to
+ * 'full'.
* @param $langcode
* (optional) A string indicating the language field values are to be shown
* 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')) {
- // To change user picture settings (e.g., image style), edit the 'compact'
- // view mode on the User entity.
+ // To change user picture settings (for instance, image style), edit the
+ // 'compact' view mode on the User entity.
$variables['user_picture'] = user_view($account, 'compact');
}
else {
diff --git a/core/modules/comment/templates/comment.html.twig b/core/modules/comment/templates/comment.html.twig
index 14c52eba0524..7f0c332974a8 100644
--- a/core/modules/comment/templates/comment.html.twig
+++ b/core/modules/comment/templates/comment.html.twig
@@ -27,7 +27,7 @@
* - title: Comment title, linked to the comment.
* - attributes: HTML attributes for the containing element.
* 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-{entity-type}-author: Comment by the author of the parent entity,
* eg. by-node-author.
diff --git a/core/modules/config_translation/src/ConfigMapperManager.php b/core/modules/config_translation/src/ConfigMapperManager.php
index 2731aa0e592d..8e605878591a 100644
--- a/core/modules/config_translation/src/ConfigMapperManager.php
+++ b/core/modules/config_translation/src/ConfigMapperManager.php
@@ -87,13 +87,14 @@ protected function getDiscovery() {
if (!isset($this->discovery)) {
// Look at all themes and modules.
// @todo If the list of installed modules and themes is changed, new
- // definitions are not picked up immediately and obsolete definitions are
- // not removed, because the list of search directories is only compiled
- // once in this constructor. The current code only works due to
- // coincidence: The request that installs e.g. a new theme does not
- // instantiate this plugin manager at the beginning of the request; when
- // routes are being rebuilt at the end of the request, this service only
- // happens to get instantiated with the updated list of installed themes.
+ // definitions are not picked up immediately and obsolete definitions
+ // are not removed, because the list of search directories is only
+ // compiled once in this constructor. The current code only works due to
+ // coincidence: The request that installs (for instance, a new theme)
+ // does not instantiate this plugin manager at the beginning of the
+ // request; when routes are being rebuilt at the end of the request,
+ // this service only happens to get instantiated with the updated list
+ // of installed themes.
$directories = array();
foreach ($this->moduleHandler->getModuleList() as $name => $module) {
$directories[$name] = $module->getPath();
diff --git a/core/modules/content_translation/content_translation.module b/core/modules/content_translation/content_translation.module
index b354e9549f0a..6e7bb706afec 100644
--- a/core/modules/content_translation/content_translation.module
+++ b/core/modules/content_translation/content_translation.module
@@ -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
* 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
- * entity type should implement its own UI. This is useful for (e.g.) entity
- * types that are embedded into others for editing (which would not need a
- * canonical link, but could still support translation).
+ * entity type should implement its own UI. For instance, this is useful for
+ * entity types that are embedded into others for editing (which would not
+ * need a canonical link, but could still support translation).
* - content_translation_metadata: To implement its business logic the content
* translation UI relies on various metadata items describing the translation
* state. The default implementation is provided by
diff --git a/core/modules/content_translation/src/ContentTranslationHandler.php b/core/modules/content_translation/src/ContentTranslationHandler.php
index 1b8d77df90c2..94505bea1ac5 100644
--- a/core/modules/content_translation/src/ContentTranslationHandler.php
+++ b/core/modules/content_translation/src/ContentTranslationHandler.php
@@ -177,8 +177,8 @@ public function getFieldDefinitions() {
protected function hasAuthor() {
// Check for field named uid, but only in case the entity implements the
// 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
- // User entity.
+ // defined as field name, but is not meant to be an owner field; for
+ // instance, the User entity.
return $this->entityType->isSubclassOf('\Drupal\user\EntityOwnerInterface') && $this->checkFieldStorageDefinitionTranslatability('uid');
}
@@ -550,7 +550,7 @@ protected function addTranslatabilityClue(&$element) {
// Update #title attribute for all elements that are allowed to have a
// #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
- // 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'])) {
$element['#title'] .= $suffix;
}
diff --git a/core/modules/file/src/Tests/FileManagedTestBase.php b/core/modules/file/src/Tests/FileManagedTestBase.php
index 07964f7ca27e..ebaaaea1b881 100644
--- a/core/modules/file/src/Tests/FileManagedTestBase.php
+++ b/core/modules/file/src/Tests/FileManagedTestBase.php
@@ -33,9 +33,9 @@ protected function setUp() {
* Assert that all of the specified hook_file_* hooks were called once, other
* values result in failure.
*
- * @param array $expected
- * Array with string containing with the hook name, e.g. 'load', 'save',
- * 'insert', etc.
+ * @param string[] $expected
+ * An array of strings containing with the hook name; for example, 'load',
+ * 'save', 'insert', etc.
*/
function assertFileHooksCalled($expected) {
\Drupal::state()->resetCache();
@@ -66,7 +66,7 @@ function assertFileHooksCalled($expected) {
* Assert that a hook_file_* hook was called a certain number of times.
*
* @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
* Optional integer count.
* @param string|NULL $message
--
GitLab