Commit aaabb05c authored by jhodgdon's avatar jhodgdon

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

parent 0fb0add6
......@@ -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.
......
......@@ -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()
......
......@@ -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.
......
......@@ -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.
*
......
......@@ -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 {
......
......@@ -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,
......
......@@ -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']
......
......@@ -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.
......
......@@ -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();
......
......@@ -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.
}
}
......
......@@ -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.
......
......@@ -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;
......
......@@ -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,
......
......@@ -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;
}
......
......@@ -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'.