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 ...@@ -341,7 +341,7 @@ Drupal 7.0, 2011-01-05
- Improved time zone support: - Improved time zone support:
* Drupal now uses PHP's time zone database when rendering dates in local * Drupal now uses PHP's time zone database when rendering dates in local
time. Site-wide and user-configured time zone offsets have been converted time. Site-wide and user-configured time zone offsets have been converted
to time zone names, e.g. Africa/Abidjan. to time zone names; for example, Africa/Abidjan.
* In some cases the upgrade and install scripts do not choose the preferred * In some cases the upgrade and install scripts do not choose the preferred
site default time zone. The automatically-selected time zone can be site default time zone. The automatically-selected time zone can be
corrected at admin/config/regional/settings. corrected at admin/config/regional/settings.
...@@ -399,7 +399,7 @@ Drupal 7.0, 2011-01-05 ...@@ -399,7 +399,7 @@ Drupal 7.0, 2011-01-05
preserved but renamed to file_unmanaged_*(). preserved but renamed to file_unmanaged_*().
* Rewrote file handling to use PHP stream wrappers to enable support for * Rewrote file handling to use PHP stream wrappers to enable support for
both public and private files and to support pluggable storage mechanisms both public and private files and to support pluggable storage mechanisms
and access to remote resources (e.g. S3 storage or Flickr photos). and access to remote resources (for example, S3 storage or Flickr photos).
* The mime_extension_mapping variable has been removed. Modules that need to * The mime_extension_mapping variable has been removed. Modules that need to
alter the default MIME type extension mappings should implement alter the default MIME type extension mappings should implement
hook_file_mimetype_mapping_alter(). hook_file_mimetype_mapping_alter().
...@@ -816,7 +816,7 @@ Drupal 4.7.0, 2006-05-01 ...@@ -816,7 +816,7 @@ Drupal 4.7.0, 2006-05-01
- Added support for PHP5's 'mysqli' extension. - Added support for PHP5's 'mysqli' extension.
- Search module: - Search module:
* Made indexer smarter and more robust. * Made indexer smarter and more robust.
* Added advanced search operators (e.g., phrase, node type, etc.). * Added advanced search operators (phrase, node type, etc.).
* Added customizable result ranking. * Added customizable result ranking.
- PostgreSQL support: - PostgreSQL support:
* Removed dependency on PL/pgSQL procedural language. * Removed dependency on PL/pgSQL procedural language.
......
This diff is collapsed.
...@@ -423,11 +423,11 @@ public static function httpClient() { ...@@ -423,11 +423,11 @@ public static function httpClient() {
* Returns the entity query object for this entity type. * Returns the entity query object for this entity type.
* *
* @param string $entity_type * @param string $entity_type
* The entity type, e.g. node, for which the query object should be * The entity type (for example, node) for which the query object should be
* returned. * returned.
* @param string $conjunction * @param string $conjunction
* AND if all conditions in the query need to apply, OR if any of them is * (optional) Either 'AND' if all conditions in the query need to apply, or
* enough. Optional, defaults to AND. * 'OR' if any of them is sufficient. Defaults to 'AND'.
* *
* @return \Drupal\Core\Entity\Query\QueryInterface * @return \Drupal\Core\Entity\Query\QueryInterface
* The query object that can query the given entity type. * The query object that can query the given entity type.
...@@ -440,11 +440,11 @@ public static function entityQuery($entity_type, $conjunction = 'AND') { ...@@ -440,11 +440,11 @@ public static function entityQuery($entity_type, $conjunction = 'AND') {
* Returns the entity query aggregate object for this entity type. * Returns the entity query aggregate object for this entity type.
* *
* @param string $entity_type * @param string $entity_type
* The entity type, e.g. node, for which the query object should be * The entity type (for example, node) for which the query object should be
* returned. * returned.
* @param string $conjunction * @param string $conjunction
* AND if all conditions in the query need to apply, OR if any of them is * (optional) Either 'AND' if all conditions in the query need to apply, or
* enough. Optional, defaults to AND. * 'OR' if any of them is sufficient. Defaults to 'AND'.
* *
* @return \Drupal\Core\Entity\Query\QueryAggregateInterface * @return \Drupal\Core\Entity\Query\QueryAggregateInterface
* The query object that can query the given entity type. * The query object that can query the given entity type.
......
...@@ -36,10 +36,11 @@ class UrlHelper { ...@@ -36,10 +36,11 @@ class UrlHelper {
* http_build_query() directly. * http_build_query() directly.
* *
* @param array $query * @param array $query
* The query parameter array to be processed, * The query parameter array to be processed; for instance,
* e.g. \Drupal::request()->query->all(). * \Drupal::request()->query->all().
* @param string $parent * @param string $parent
* Internal use only. Used to build the $query array key for nested items. * (optional) Internal use only. Used to build the $query array key for
* nested items. Defaults to an empty string.
* *
* @return string * @return string
* A rawurlencoded string which can be used as or appended to the URL query * A rawurlencoded string which can be used as or appended to the URL query
...@@ -168,8 +169,8 @@ public static function parse($url) { ...@@ -168,8 +169,8 @@ public static function parse($url) {
} }
// Internal URLs. // Internal URLs.
else { else {
// parse_url() does not support relative URLs, so make it absolute. E.g. the // parse_url() does not support relative URLs, so make it absolute. For
// relative URL "foo/bar:1" isn't properly parsed. // instance, the relative URL "foo/bar:1" isn't properly parsed.
$parts = parse_url('http://example.com/' . $url); $parts = parse_url('http://example.com/' . $url);
// Strip the leading slash that was just added. // Strip the leading slash that was just added.
$options['path'] = substr($parts['path'], 1); $options['path'] = substr($parts['path'], 1);
...@@ -200,10 +201,11 @@ public static function encodePath($path) { ...@@ -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 * An example of an external path is http://example.com. If a path cannot be
* treat it as potentially insecure. * assessed by Drupal's menu handler, then we must treat it as potentially
* insecure.
* *
* @param string $path * @param string $path
* The internal path or external URL being linked to, such as "node/34" or * The internal path or external URL being linked to, such as "node/34" or
...@@ -296,7 +298,7 @@ public static function setAllowedProtocols(array $protocols = array()) { ...@@ -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 * This function must be called for all URIs within user-entered input prior
* to being output to an HTML attribute value. It is often called as part of * to being output to an HTML attribute value. It is often called as part of
...@@ -316,8 +318,8 @@ public static function setAllowedProtocols(array $protocols = array()) { ...@@ -316,8 +318,8 @@ public static function setAllowedProtocols(array $protocols = array()) {
* for well-formed URLs will be invoked, which strips most substrings that * for well-formed URLs will be invoked, which strips most substrings that
* precede a ":". The result can be used in URL attributes such as "href" * precede a ":". The result can be used in URL attributes such as "href"
* or "src" (only after calling Html::escape() separately), but this may not * or "src" (only after calling Html::escape() separately), but this may not
* produce valid HTML (e.g., malformed URLs within "href" attributes fail * produce valid HTML (for example, malformed URLs within "href" attributes
* HTML validation). This can be avoided by using * fail HTML validation). This can be avoided by using
* Url::fromUri($possibly_not_a_url)->toString(), which either throws an * Url::fromUri($possibly_not_a_url)->toString(), which either throws an
* exception or returns a well-formed URL. * exception or returns a well-formed URL.
* *
......
...@@ -13,8 +13,9 @@ ...@@ -13,8 +13,9 @@
* Restrict authentication methods to a subset of the site. * Restrict authentication methods to a subset of the site.
* *
* Some authentication methods should not be available throughout a whole site. * Some authentication methods should not be available throughout a whole site.
* E.g., there are good reasons to restrict insecure methods like HTTP basic * For instance, there are good reasons to restrict insecure methods like HTTP
* auth or an URL token authentication method to API-only routes. * basic authentication or an URL token authentication method to API-only
* routes.
*/ */
interface AuthenticationProviderFilterInterface { interface AuthenticationProviderFilterInterface {
......
...@@ -17,9 +17,9 @@ interface CacheableResponseInterface { ...@@ -17,9 +17,9 @@ interface CacheableResponseInterface {
/** /**
* Adds a dependency on an object: merges its cacheability metadata. * Adds a dependency on an object: merges its cacheability metadata.
* *
* E.g. when a response depends on some configuration, an entity, or an access * For instance, when a response depends on some configuration, an entity, or
* result, we must make sure their cacheability metadata is present on the * an access result, we must make sure their cacheability metadata is present
* response. This method makes doing that simple. * on the response. This method makes doing that simple.
* *
* @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $dependency * @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $dependency
* The dependency. If the object implements CacheableDependencyInterface, * The dependency. If the object implements CacheableDependencyInterface,
......
...@@ -92,9 +92,10 @@ public function getLabels($include_calculated_cache_contexts = FALSE) { ...@@ -92,9 +92,10 @@ public function getLabels($include_calculated_cache_contexts = FALSE) {
* *
* A cache context token is either: * A cache context token is either:
* - a cache context ID (if the service ID is 'cache_context.foo', then 'foo' * - a cache context ID (if the service ID is 'cache_context.foo', then 'foo'
* is a cache context ID), e.g. 'foo' * is a cache context ID); for example, 'foo'.
* - a calculated cache context ID, followed by a double colon, followed by * - a calculated cache context ID, followed by a colon, followed by
* the parameter for the calculated cache context, e.g. 'bar:some_parameter' * the parameter for the calculated cache context; for example,
* 'bar:some_parameter'.
* *
* @param string[] $context_tokens * @param string[] $context_tokens
* An array of cache context tokens. * An array of cache context tokens.
...@@ -142,11 +143,12 @@ public function convertTokensToKeys(array $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 * If a cache context is being optimized away, it is able to set cacheable
* metadata for itself which will be bubbled up. * metadata for itself which will be bubbled up.
* *
* E.g. when caching per user ('user'), also caching per role ('user.roles') * For example, when caching per user ('user'), also caching per role
* is meaningless because "per role" is implied by "per user". * ('user.roles') is meaningless because "per role" is implied by "per user".
* *
* Examples — remember that the period indicates hierarchy and the colon can * In the following examples, remember that the period indicates hierarchy and
* be used to get a specific value of a calculated cache context: * the colon can be used to get a specific value of a calculated cache
* context:
* - ['a', 'a.b'] -> ['a'] * - ['a', 'a.b'] -> ['a']
* - ['a', 'a.b.c'] -> ['a'] * - ['a', 'a.b.c'] -> ['a']
* - ['a.b', 'a.b.c'] -> ['a.b'] * - ['a.b', 'a.b.c'] -> ['a.b']
......
...@@ -18,10 +18,10 @@ interface ConfigEntityStorageInterface extends EntityStorageInterface { ...@@ -18,10 +18,10 @@ interface ConfigEntityStorageInterface extends EntityStorageInterface {
* Extracts the configuration entity ID from the full configuration name. * Extracts the configuration entity ID from the full configuration name.
* *
* @param string $config_name * @param string $config_name
* The full configuration name to extract the ID from. E.g. * The full configuration name to extract the ID from; for example,
* 'views.view.archive'. * 'views.view.archive'.
* @param string $config_prefix * @param string $config_prefix
* The config prefix of the configuration entity. E.g. 'views.view' * The config prefix of the configuration entity; for example, 'views.view'.
* *
* @return string * @return string
* The ID of the configuration entity. * The ID of the configuration entity.
......
...@@ -80,9 +80,9 @@ public function __construct($directory = self::CONFIG_INSTALL_DIRECTORY, $collec ...@@ -80,9 +80,9 @@ public function __construct($directory = self::CONFIG_INSTALL_DIRECTORY, $collec
* The path to the configuration file. * The path to the configuration file.
* *
* @todo Improve this when figuring out how we want to handle configuration in * @todo Improve this when figuring out how we want to handle configuration in
* installation profiles. E.g., a config object actually has to be searched * installation profiles. For instance, a config object actually has to be
* in the profile first (whereas the profile is never the owner), only * searched in the profile first (whereas the profile is never the owner);
* afterwards check for a corresponding module or theme. * only afterwards check for a corresponding module or theme.
*/ */
public function getFilePath($name) { public function getFilePath($name) {
$folders = $this->getAllFolders(); $folders = $this->getAllFolders();
......
...@@ -160,8 +160,8 @@ protected function wrapControllerExecutionInRenderContext($controller, array $ar ...@@ -160,8 +160,8 @@ protected function wrapControllerExecutionInRenderContext($controller, array $ar
} }
else { else {
// A Response or domain object is returned that does not care about // A Response or domain object is returned that does not care about
// attachments nor cacheability. E.g. a RedirectResponse. It is safe to // attachments nor cacheability; for instance, a RedirectResponse. It is
// discard any early rendering metadata. // safe to discard any early rendering metadata.
} }
} }
......
...@@ -86,9 +86,12 @@ public function getToolkitId(); ...@@ -86,9 +86,12 @@ public function getToolkitId();
* @param string $operation * @param string $operation
* The operation to be performed against the image. * The operation to be performed against the image.
* @param array $arguments * @param array $arguments
* An associative array of arguments to be passed to the toolkit * (optional) An associative array of arguments to be passed to the toolkit
* operation, e.g. array('width' => 50, 'height' => 100, * operation; for instance,
* 'upscale' => TRUE). * @code
* ['width' => 50, 'height' => 100, 'upscale' => TRUE]
* @endcode
* Defaults to an empty array.
* *
* @return bool * @return bool
* TRUE on success, FALSE on failure. * TRUE on success, FALSE on failure.
...@@ -120,11 +123,11 @@ public function save($destination = NULL); ...@@ -120,11 +123,11 @@ public function save($destination = NULL);
* @param int $height * @param int $height
* The height of the new image, in pixels. * The height of the new image, in pixels.
* @param string $extension * @param string $extension
* (Optional) The extension of the image file (e.g. 'png', 'gif', etc.). * (optional) The extension of the image file (for instance, 'png', 'gif',
* Allowed values depend on the implementation of the image toolkit. * etc.). Allowed values depend on the implementation of the image toolkit.
* Defaults to 'png'. * Defaults to 'png'.
* @param string $transparent_color * @param string $transparent_color
* (Optional) The hexadecimal string representing the color to be used * (optional) The hexadecimal string representing the color to be used
* for transparency, needed for GIF images. Defaults to '#ffffff' (white). * for transparency, needed for GIF images. Defaults to '#ffffff' (white).
* *
* @return bool * @return bool
...@@ -176,8 +179,8 @@ public function scaleAndCrop($width, $height); ...@@ -176,8 +179,8 @@ public function scaleAndCrop($width, $height);
* extension. * extension.
* *
* @param string $extension * @param string $extension
* The extension to convert to (e.g. 'jpeg' or 'png'). Allowed values depend * The extension to convert to (for instance, 'jpeg' or 'png'). Allowed
* on the current image toolkit. * values depend on the current image toolkit.
* *
* @return bool * @return bool
* TRUE on success, FALSE on failure. * TRUE on success, FALSE on failure.
...@@ -231,10 +234,10 @@ public function desaturate(); ...@@ -231,10 +234,10 @@ public function desaturate();
* The number of (clockwise) degrees to rotate the image. * The number of (clockwise) degrees to rotate the image.
* @param string|null $background * @param string|null $background
* (optional) An hexadecimal integer specifying the background color to use * (optional) An hexadecimal integer specifying the background color to use
* for the uncovered area of the image after the rotation. E.g. 0x000000 for * for the uncovered area of the image after the rotation; for example,
* black, 0xff00ff for magenta, and 0xffffff for white. For images that * 0x000000 for black, 0xff00ff for magenta, and 0xffffff for white. When
* support transparency, this will default to transparent. Otherwise it will * NULL (the default) is specified, for images that support transparency,
* be white. * this will default to transparent; otherwise, it will default to white.
* *
* @return bool * @return bool
* TRUE on success, FALSE on failure. * TRUE on success, FALSE on failure.
......
...@@ -297,8 +297,8 @@ public static function htmlToText($string, $allowed_tags = NULL) { ...@@ -297,8 +297,8 @@ public static function htmlToText($string, $allowed_tags = NULL) {
* Note that we are skipping MIME content header lines, because attached * Note that we are skipping MIME content header lines, because attached
* files, especially applications, could have long MIME types or long * files, especially applications, could have long MIME types or long
* filenames which result in line length longer than the 77 characters limit * filenames which result in line length longer than the 77 characters limit
* and wrapping that line will break the email format. E.g., the attached file * and wrapping that line will break the email format. For instance, the
* hello_drupal.docx will produce the following Content-Type: * attached file hello_drupal.docx will produce the following Content-Type:
* @code * @code
* Content-Type: * Content-Type:
* application/vnd.openxmlformats-officedocument.wordprocessingml.document; * application/vnd.openxmlformats-officedocument.wordprocessingml.document;
......
...@@ -32,9 +32,9 @@ public function getContextData(); ...@@ -32,9 +32,9 @@ public function getContextData();
/** /**
* Adds a dependency on an object: merges its cacheability metadata. * Adds a dependency on an object: merges its cacheability metadata.
* *
* E.g. when a context depends on some configuration, an entity, or an access * For example, when a context depends on some configuration, an entity, or an
* result, we must make sure their cacheability metadata is present on the * access result, we must make sure their cacheability metadata is present on
* response. This method makes doing that simple. * the response. This method makes doing that simple.
* *
* @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $dependency * @param \Drupal\Core\Cache\CacheableDependencyInterface|mixed $dependency
* The dependency. If the object implements CacheableDependencyInterface, * The dependency. If the object implements CacheableDependencyInterface,
......
...@@ -120,13 +120,13 @@ protected function getPluginNamespaces() { ...@@ -120,13 +120,13 @@ protected function getPluginNamespaces() {
if ($this->namespaceSuffix) { if ($this->namespaceSuffix) {
foreach ($this->rootNamespacesIterator as $namespace => $dirs) { foreach ($this->rootNamespacesIterator as $namespace => $dirs) {
// Append the namespace suffix to the base namespace, to obtain the // Append the namespace suffix to the base namespace, to obtain the
// plugin namespace. E.g. 'Drupal\Views' may become // plugin namespace; for example, 'Drupal\Views' may become
// 'Drupal\Views\Plugin\Block'. // 'Drupal\Views\Plugin\Block'.
$namespace .= $this->namespaceSuffix; $namespace .= $this->namespaceSuffix;
foreach ((array) $dirs as $dir) { foreach ((array) $dirs as $dir) {
// Append the directory suffix to the PSR-4 base directory, to obtain // Append the directory suffix to the PSR-4 base directory, to obtain
// the directory where plugins are found. // the directory where plugins are found. For example,
// E.g. DRUPAL_ROOT . '/core/modules/views/src' may become // DRUPAL_ROOT . '/core/modules/views/src' may become
// DRUPAL_ROOT . '/core/modules/views/src/Plugin/Block'. // DRUPAL_ROOT . '/core/modules/views/src/Plugin/Block'.
$plugin_namespaces[$namespace][] = $dir . $this->directorySuffix; $plugin_namespaces[$namespace][] = $dir . $this->directorySuffix;
} }
......
...@@ -47,8 +47,8 @@ class YamlDiscovery implements DiscoveryInterface { ...@@ -47,8 +47,8 @@ class YamlDiscovery implements DiscoveryInterface {
* Construct a YamlDiscovery object. * Construct a YamlDiscovery object.
* *
* @param string $name * @param string $name
* The file name suffix to use for discovery. E.g. 'test' will become * The file name suffix to use for discovery; for example, 'test' will
* 'MODULE.test.yml'. * become 'MODULE.test.yml'.
* @param array $directories * @param array $directories
* An array of directories to scan. * An array of directories to scan.
*/ */
......
...@@ -30,8 +30,8 @@ class YamlDiscoveryDecorator extends YamlDiscovery { ...@@ -30,8 +30,8 @@ class YamlDiscoveryDecorator extends YamlDiscovery {
* @param \Drupal\Component\Plugin\Discovery\DiscoveryInterface $decorated * @param \Drupal\Component\Plugin\Discovery\DiscoveryInterface $decorated
* The discovery object that is being decorated. * The discovery object that is being decorated.
* @param string $name * @param string $name
* The file name suffix to use for discovery. E.g. 'test' will become * The file name suffix to use for discovery; for instance, 'test' will
* 'MODULE.test.yml'. * become 'MODULE.test.yml'.
* @param array $directories * @param array $directories
* An array of directories to scan. * An array of directories to scan.
*/ */
......
...@@ -42,9 +42,9 @@ public function renderRoot(&$elements); ...@@ -42,9 +42,9 @@ public function renderRoot(&$elements);
* *
* Calls ::render() in such a way that placeholders are replaced. * Calls ::render() in such a way that placeholders are replaced.
* *
* Useful for e.g. rendering the values of tokens or emails, which need a * Useful for instance when rendering the values of tokens or emails, which
* render array being turned into a string, but don't need any of the * need a render array being turned into a string, but do not need any of the
* bubbleable metadata (the attached assets the cache tags). * bubbleable metadata (the attached assets and cache tags).
* *
* Some of these are a relatively common use case and happen *within* a * Some of these are a relatively common use case and happen *within* a
* ::renderRoot() call, but that is generally highly problematic (and hence an * ::renderRoot() call, but that is generally highly problematic (and hence an
...@@ -138,8 +138,8 @@ public function renderPlaceholder($placeholder, array $elements); ...@@ -138,8 +138,8 @@ public function renderPlaceholder($placeholder, array $elements);
* - 'keys': An array of one or more keys that identify the element. If * - 'keys': An array of one or more keys that identify the element. If
* 'keys' is set, the cache ID is created automatically from these keys. * 'keys' is set, the cache ID is created automatically from these keys.
* - 'contexts': An array of one or more cache context IDs. These are * - 'contexts': An array of one or more cache context IDs. These are
* converted to a final value depending on the request. (e.g. 'user' is * converted to a final value depending on the request. (For instance,
* mapped to the current user's ID.) * 'user' is mapped to the current user's ID.)
* - 'max-age': A time in seconds. Zero seconds means it is not cacheable. * - 'max-age': A time in seconds. Zero seconds means it is not cacheable.
* \Drupal\Core\Cache\Cache::PERMANENT means it is cacheable forever. * \Drupal\Core\Cache\Cache::PERMANENT means it is cacheable forever.
* - 'bin': Specify a cache bin to cache the element in. Default is * - 'bin': Specify a cache bin to cache the element in. Default is
...@@ -298,14 +298,14 @@ public function renderPlaceholder($placeholder, array $elements); ...@@ -298,14 +298,14 @@ public function renderPlaceholder($placeholder, array $elements);
* placeholder element containing a #lazy_builder function is rendered in * placeholder element containing a #lazy_builder function is rendered in
* isolation. The resulting markup is used to replace the placeholder, and * isolation. The resulting markup is used to replace the placeholder, and
* any bubbleable metadata is merged. * any bubbleable metadata is merged.
* Placeholders must be unique, to guarantee that e.g. samples of * Placeholders must be unique, to guarantee that for instance, samples of
* placeholders are not replaced as well. * placeholders are not replaced as well.
* - Just before finishing the rendering of this element, this element's * - Just before finishing the rendering of this element, this element's
* stack frame (the topmost one) is bubbled: the two topmost frames are * stack frame (the topmost one) is bubbled: the two topmost frames are
* popped from the stack, they are merged and the result is pushed back * popped from the stack, they are merged and the result is pushed back
* onto the stack. * onto the stack.
* So if this element e.g. was a child element, then a new frame was * So if for instance this element was a child element, then a new frame
* pushed onto the stack element at the beginning of rendering this * was pushed onto the stack element at the beginning of rendering this
* element, it was updated when the rendering was completed, and now we * element, it was updated when the rendering was completed, and now we
* merge it with the frame for the parent, so that the parent now has the * merge it with the frame for the parent, so that the parent now has the
* bubbleable rendering metadata for its child. * bubbleable rendering metadata for its child.
...@@ -401,9 +401,9 @@ public function mergeBubbleableMetadata(array $a, array $b); ...@@ -401,9 +401,9 @@ public function mergeBubbleableMetadata(array $a, array $b);
/** /**
* Adds a dependency on an object: merges its cacheability metadata. * Adds a dependency on an object: merges its cacheability metadata.
* *
* E.g. when a render array depends on some configuration, an entity, or an * For instance, when a render array depends on some configuration, an entity,
* access result, we must make sure their cacheability metadata is present on * or an access result, we must make sure their cacheability metadata is
* the render array. This method makes doing that simple. * present on the render array. This method makes doing that simple.
* *
* @param array &$elements * @param array &$elements
* The render array to update. * The render array to update.
......
...@@ -66,8 +66,10 @@ interface StreamWrapperInterface extends PhpStreamWrapperInterface { ...@@ -66,8 +66,10 @@ interface StreamWrapperInterface extends PhpStreamWrapperInterface {
*/ */
/** /**
* Not visible in the UI or accessible via web, but readable and writable. * Defines the stream wrapper bit flag for a hidden file.
* E.g. the temporary directory for uploads. *
* This is not visible in the UI or accessible via web, but readable and
* writable; for instance, the temporary directory for file uploads.
*/ */
const HIDDEN = 0x000C; const HIDDEN = 0x000C;
......
...@@ -315,8 +315,8 @@ public function getActiveThemePath() { ...@@ -315,8 +315,8 @@ public function getActiveThemePath() {
* ampersand ("&") which separates query params. Thus we cannot mark * ampersand ("&") which separates query params. Thus we cannot mark
* the generated URL as always safe, but only when we are sure there won't be * the generated URL as always safe, but only when we are sure there won't be
* multiple query params. This is the case when there are none or only one * multiple query params. This is the case when there are none or only one
* constant parameter given. E.g. we know beforehand this will not need to * constant parameter given. For instance, we know beforehand this will not
* be escaped: * need to be escaped:
* - path('route') * - path('route')
* - path('route', {'param': 'value'}) * - path('route', {'param': 'value'})
* But the following may need to be escaped: * But the following may need to be escaped:
......
...@@ -78,7 +78,7 @@ public function create(DataDefinitionInterface $definition, $value = NULL, $name ...@@ -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 * class used by a data type is known, this method allows the creation of data
* definitions for any given data type. * definitions for any given data type.
* *
* E.g., if a definition for a map is to be created, the following code * For example, if a definition for a map is to be created, the following code
* could be used instead of calling this method with the argument 'map': * could be used instead of calling this method with the argument 'map':
* @code * @code
* $map_definition = \Drupal\Core\TypedData\MapDataDefinition::create(); * $map_definition = \Drupal\Core\TypedData\MapDataDefinition::create();
...@@ -137,9 +137,10 @@ public function getInstance(array $options); ...@@ -137,9 +137,10 @@ public function getInstance(array $options);
* Get a typed data instance for a property of a given typed data object. * Get a typed data instance for a property of a given typed data object.
* *
* This method will use prototyping for fast and efficient instantiation of * This method will use prototyping for fast and efficient instantiation of
* many property objects with the same property path; e.g., * many property objects with the same property path; for example,
* when multiple comments are used comment_body.0.value needs to be * when multiple comments are used comment_body.0.value needs to be
* instantiated very often. * instantiated very often.
*
* Prototyping is done by the root object's data type and the given * Prototyping is done by the root object's data type and the given
* property path, i.e. all property instances having the same property path * property path, i.e. all property instances having the same property path
* and inheriting from the same data type are prototyped. * and inheriting from the same data type are prototyped.
...@@ -203,9 +204,10 @@ public function setValidationConstraintManager(ConstraintManager $constraintMana ...@@ -203,9 +204,10 @@ public function setValidationConstraintManager(ConstraintManager $constraintMana
* Gets default constraints for the given data definition. * Gets default constraints for the given data definition.
* *
* This generates default constraint definitions based on the data definition; * This generates default constraint definitions based on the data definition;
* e.g. a NotNull constraint is generated if the data is defined as required. * for example, a NotNull constraint is generated if the data is defined as
* Besides that any constraints defined for the data type, i.e. below the * required. Besides that, any constraints defined for the data type (that is,
* 'constraint' key of the type's plugin definition, are taken into account. * below the 'constraint' key of the type's plugin definition) are taken into
* account.
* *
* @param \Drupal\Core\TypedData\DataDefinitionInterface $definition * @param \Drupal\Core\TypedData\DataDefinitionInterface $definition
* A data definition. * A data definition.
...@@ -222,12 +224,12 @@ public function getDefaultConstraints(DataDefinitionInterface $definition); ...@@ -222,12 +224,12 @@ public function getDefaultConstraints(DataDefinitionInterface $definition);
* *
* The canonical representation is typically used when data is passed on to * The canonical representation is typically used when data is passed on to
* other code components. In many use cases, the TypedData object is mostly * other code components. In many use cases, the TypedData object is mostly
* unified adapter wrapping a primary value (e.g. a string, an entity...)