Update to Drupal 8.0.2. For more information, see https://www.drupal.org/drupal-8.0.2-release-notes

core/lib/Drupal/Core/Render/Element/HtmlTag.php

@@ -16,6 +16,24 @@ use Drupal\Core\Template\Attribute;
 /**
  * Provides a render element for any HTML tag, with properties and value.
  *
+ * Properties:
+ * - #tag: The tag name to output.
+ * - #attributes: (array, optional) HTML attributes to apply to the tag. The
+ *   attributes are escaped, see \Drupal\Core\Template\Attribute.
+ * - #value: (string, optional) A string containing the textual contents of
+ *   the tag.
+ * - #noscript: (bool, optional) When set to TRUE, the markup
+ *   (including any prefix or suffix) will be wrapped in a <noscript> element.
+ *
+ * Usage example:
+ * @code
+ * $build['hello'] = [
+ *   '#type' => 'html_tag'
+ *   '#tag' => 'p',
+ *   '#value' => $this->t('Hello World'),
+ * ];
+ * @endcode
+ *
  * @RenderElement("html_tag")
  */
 class HtmlTag extends RenderElement {

core/lib/Drupal/Core/Render/Element/InlineTemplate.php

@@ -10,6 +10,22 @@ namespace Drupal\Core\Render\Element;
 /**
  * Provides a render element where the user supplies an in-line Twig template.
  *
+ * Properties:
+ * - #template: The inline Twig template used to render the element.
+ * - #context: (array) The variables to substitute into the Twig template.
+ *   Each variable may be a string or a render array.
+ *
+ * Usage example:
+ * @code
+ * $build['hello']  = [
+ *   '#type' => 'inline_template',
+ *   '#template' => "{% trans %} Hello {% endtrans %} <strong>{{name}}</strong>",
+ *   '#context' => [
+ *     'name' => $name,
+ *   ]
+ * ];
+ * @endcode
+ *
  * @RenderElement("inline_template")
  */
 class InlineTemplate extends RenderElement {

core/lib/Drupal/Core/Render/Element/Label.php

@@ -11,7 +11,8 @@ namespace Drupal\Core\Render\Element;
  * Provides a render element for displaying the label for a form element.
  *
  * Labels are generated automatically from element properties during processing
- * of most form elements.
+ * of most form elements. This element is used internally by the form system
+ * to render labels for form elements.
  *
  * @RenderElement("label")
  */

core/lib/Drupal/Core/Render/Element/Link.php

@@ -15,6 +15,20 @@ use Drupal\Core\Url as CoreUrl;
 /**
  * Provides a link render element.
  *
+ * Properties:
+ * - #title: The link text.
+ * - #url: \Drupal\Url object containing URL information pointing to a internal
+ *   or external link . See \Drupal\Core\Utility\LinkGeneratorInterface.
+ *
+ * Usage example:
+ * @code
+ * $build['examples_link'] = [
+ *   '#title' => $this->t('Examples'),
+ *   '#type' => 'link',
+ *   '#url' => Url::fromRoute('examples.description')
+ * ];
+ * @endcode
+ *
  * @RenderElement("link")
  */
 class Link extends RenderElement {

core/lib/Drupal/Core/Render/Element/MoreLink.php

@@ -10,6 +10,19 @@ namespace Drupal\Core\Render\Element;
 /**
  * Provides a link render element for a "more" link, like those used in blocks.
  *
+ * Properties:
+ * - #title: The text of the link to generate (defaults to 'More').
+ *
+ * See \Drupal\Core\Render\Element\Link for additional properties.
+ *
+ * Usage Example:
+ * @code
+ * $build['more'] = [
+ *   '#type' => 'more_link',
+ *   '#url' => Url::fromRoute('examples.more_examples')
+ * ]
+ * @endcode
+ *
  * @RenderElement("more_link")
  */
 class MoreLink extends Link {

core/lib/Drupal/Core/Render/Element/Pager.php

@@ -12,6 +12,29 @@ use Drupal\Core\Render\Element;
 /**
  * Provides a render element for a pager.
  *
+ * The pager must be initialized with a call to pager_default_initialize() in
+ * order to render properly. When used with database queries, this is performed
+ * for you when you extend a select query with
+ * \Drupal\Core\Database\Query\PagerSelectExtender.
+ *
+ * Properties:
+ * - #element: (optional, int) The pager ID, to distinguish between multiple
+ *   pagers on the same page (defaults to 0).
+ * - #parameters: (optional) An associative array of query string parameters to
+ *   append to the pager.
+ * - #quantity: The maximum number of numbered page links to create (defaults
+ *   to 9).
+ * - #tags: (optional) An array of labels for the controls in the pages.
+ * - #route_name: (optional) The name of the route to be used to build pager
+ *   links. Defaults to '<none>', which will make links relative to the current
+ *   URL. This makes the page more effectively cacheable.
+ *
+ * @code
+ * $build['pager'] = [
+ *   '#type' => 'pager',
+ * ];
+ * @endcode
+ *
  * @RenderElement("pager")
  */
 class Pager extends RenderElement{

core/lib/Drupal/Core/Render/Element/Select.php

@@ -14,12 +14,30 @@ use Drupal\Core\Render\Element;
  * Provides a form element for a drop-down menu or scrolling selection box.
  *
  * Properties:
- * - #options: An associative array, where the keys are the retured values for
- *   each option, and the values are the options to be shown in the drop-down
- *   list.
+ * - #options: An associative array, where the keys are the values for each
+ *   option, and the values are the option labels to be shown in the drop-down
+ *   list. If a value is an array, it will be rendered similarly, but as an
+ *   optgroup. The key of the sub-array will be used as the label for the
+ *   optgroup. Nesting optgroups is not allowed.
  * - #empty_option: The label that will be displayed to denote no selection.
  * - #empty_value: The value of the option that is used to denote no selection.
  *
+ * Usage example:
+ * @code
+ * $form['example_select'] = [
+ *   '#type' => 'select',
+ *   '#title' => t('Select element'),
+ *   '#options' => [
+ *     '1' => t('One'),
+ *     '2' => [
+ *       '2.1' => t('Two point one'),
+ *       '2.2' => t('Two point two'),
+ *     ],
+ *     '3' => t('Three'),
+ *   ],
+ * ];
+ * @endcode
+ *
  * @FormElement("select")
  */
 class Select extends FormElement {

core/lib/Drupal/Core/Render/Element/StatusMessages.php

@@ -10,6 +10,15 @@ namespace Drupal\Core\Render\Element;
 /**
  * Provides a messages element.
  *
+ * Used to display results of drupal_set_message() calls.
+ *
+ * Usage example:
+ * @code
+ * $build['status_messages'] = [
+ *   '#type' => 'status_messages',
+ * ];
+ * @end
+ *
  * @RenderElement("status_messages")
  */
 class StatusMessages extends RenderElement {

core/lib/Drupal/Core/Render/Element/SystemCompactLink.php

@@ -11,7 +11,14 @@ use Drupal\Core\Url as BaseUrl;
 use Drupal\Component\Utility\NestedArray;
 
 /**
- * Provides a link render element to show or hide inline help descriptions.
+ * Provides a link to show or hide help text on administration pages.
+ *
+ * Usage example:
+ * @code
+ * $form['system_compact_link'] = [
+ *   '#type' => 'system_compact_link',
+ * ];
+ * @endcode
  *
  * @RenderElement("system_compact_link")
  */

core/lib/Drupal/Core/Render/PlaceholderGenerator.php

@@ -49,19 +49,19 @@ class PlaceholderGenerator implements PlaceholderGeneratorInterface {
    * {@inheritdoc}
    */
   public function shouldAutomaticallyPlaceholder(array $element) {
+    // Auto-placeholder if the max-age, cache context or cache tag is specified
+    // in the auto-placeholder conditions in the 'renderer.config' container
+    // parameter.
     $conditions = $this->rendererConfig['auto_placeholder_conditions'];
 
-    // Auto-placeholder if max-age is at or below the configured threshold.
     if (isset($element['#cache']['max-age']) && $element['#cache']['max-age'] !== Cache::PERMANENT && $element['#cache']['max-age'] <= $conditions['max-age']) {
       return TRUE;
     }
 
-    // Auto-placeholder if a high-cardinality cache context is set.
     if (isset($element['#cache']['contexts']) && array_intersect($element['#cache']['contexts'], $conditions['contexts'])) {
       return TRUE;
     }
 
-    // Auto-placeholder if a high-invalidation frequency cache tag is set.
     if (isset($element['#cache']['tags']) && array_intersect($element['#cache']['tags'], $conditions['tags'])) {
       return TRUE;
     }

core/lib/Drupal/Core/Render/PlaceholderGeneratorInterface.php

@@ -35,6 +35,11 @@ interface PlaceholderGeneratorInterface {
   /**
    * Whether the given render array should be automatically placeholdered.
    *
+   * The render array should be placeholdered if its cacheability either has a
+   * cache context with too high cardinality, a cache tag with a too high
+   * invalidation rate, or a max-age that is too low. Either of these would make
+   * caching ineffective, and thus we choose to placeholder instead.
+   *
    * @param array $element
    *   The render array whose cacheability to analyze.
    *

core/lib/Drupal/Core/Render/RendererInterface.php

@@ -42,9 +42,9 @@ interface RendererInterface {
    *
    * 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 @@ interface RendererInterface {
    *     - '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 @@ interface RendererInterface {
    *     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 @@ interface RendererInterface {
   /**
    * 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.

core/lib/Drupal/Core/Render/theme.api.php

@@ -37,16 +37,16 @@
  * http://twig.sensiolabs.org/doc/templates.html
  *
  * @section sec_theme_hooks Theme Hooks
- * The theme system is invoked in drupal_render() by calling the internal
- * _theme() function, which operates on the concept of "theme hooks". Theme
- * hooks define how a particular type of data should be rendered. They are
- * registered by modules by implementing hook_theme(), which specifies the name
- * of the hook, the input "variables" used to provide data and options, and
- * other information. Modules implementing hook_theme() also need to provide a
- * default implementation for each of their theme hooks, normally in a Twig
- * file, and they may also provide preprocessing functions. For example, the
- * core Search module defines a theme hook for a search result item in
- * search_theme():
+ * The theme system is invoked in \Drupal\Core\Render\Renderer::doRender() by
+ * calling the \Drupal\Core\Theme\ThemeManagerInterface::render() function,
+ * which operates on the concept of "theme hooks". Theme hooks define how a
+ * particular type of data should be rendered. They are registered by modules by
+ * implementing hook_theme(), which specifies the name of the hook, the input
+ * "variables" used to provide data and options, and other information. Modules
+ * implementing hook_theme() also need to provide a default implementation for
+ * each of their theme hooks, normally in a Twig file, and they may also provide
+ * preprocessing functions. For example, the core Search module defines a theme
+ * hook for a search result item in search_theme():
  * @code
  * return array(
  *   'search_result' => array(
@@ -366,7 +366,7 @@
  * @code
  *   '#cache' => [
  *     'keys' => ['entity_view', 'node', $node->id()],
- *     'contexts' => ['language'],
+ *     'contexts' => ['languages'],
  *     'tags' => ['node:' . $node->id()],
  *     'max-age' => Cache::PERMANENT,
  *   ],
@@ -429,9 +429,10 @@
  *
  * @section render_pipeline The render pipeline
  * The term "render pipeline" refers to the process Drupal uses to take
- * information provided by modules and render it into a response. For more
- * details on this process, see https://www.drupal.org/developing/api/8/render;
- * for background on routing concepts, see @ref sec_controller.
+ * information provided by modules and render it into a response. See
+ * https://www.drupal.org/developing/api/8/render for more details on this
+ * process. For background on routing concepts, see
+ * @link routing Routing API. @endlink
  *
  * There are in fact multiple render pipelines:
  * - Drupal always uses the Symfony render pipeline. See
@@ -472,6 +473,36 @@
  * @}
  */
 
+/**
+ * @defgroup listing_page_element Page header for Elements page
+ * @{
+ * Introduction to form and render elements
+ *
+ * Render elements are referenced in render arrays. Render arrays contain data
+ * to be rendered, along with meta-data and attributes that specify how to
+ * render the data into markup; see the
+ * @link theme_render Render API topic @endlink for an overview of render
+ * arrays and render elements. Form arrays are a subset of render arrays,
+ * representing HTML forms; form elements are a subset of render elements,
+ * representing HTML elements for forms. See the
+ * @link form_api Form API topic @endlink for an overview of forms, form
+ * processing, and form arrays.
+ *
+ * Each form and render element type corresponds to an element plugin class;
+ * each of them either extends \Drupal\Core\Render\Element\RenderElement
+ * (render elements) or \Drupal\Core\Render\Element\FormElement (form
+ * elements). Usage and properties are documented on the individual classes,
+ * and the two base classes list common properties shared by all render
+ * elements and the form element subset, respectively.
+ *
+ * @see theme_render
+ * @see form_api
+ * @see \Drupal\Core\Render\Element\RenderElement
+ * @see \Drupal\Core\Render\Element\FormElement
+ *
+ * @}
+ */
+
 /**
  * @addtogroup hooks
  * @{
@@ -512,7 +543,8 @@ function hook_form_system_theme_settings_alter(&$form, \Drupal\Core\Form\FormSta
  * preprocess variables for a specific theme hook, whether implemented as a
  * template or function.
  *
- * For more detailed information, see _theme().
+ * For more detailed information, see the
+ * @link themeable Theme system overview topic @endlink.
  *
  * @param $variables
  *   The variables array (modify in place).
@@ -560,7 +592,8 @@ function hook_preprocess(&$variables, $hook) {
  * hook. It should only be used if a module needs to override or add to the
  * theme preprocessing for a theme hook it didn't define.
  *
- * For more detailed information, see _theme().
+ * For more detailed information, see the
+ * @link themeable Theme system overview topic @endlink.
  *
  * @param $variables
  *   The variables array (modify in place).