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.
......
This diff is collapsed.
......@@ -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'.
* @param array $directories
* An array of directories to scan.
*/
......
......@@ -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.
*/
......
......@@ -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.
......
......@@ -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;
......
......@@ -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:
......
......@@ -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
......
......@@ -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
......
......@@ -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;
}
......
......@@ -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.
*
......
......@@ -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'],
......
......@@ -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.
......
......@@ -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
......
......@@ -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'])) {
......
......@@ -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]);
......
......@@ -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 {
......
......@@ -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.
......
......@@ -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();
......
......@@ -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
......
......@@ -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;
}
......
......@@ -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.