Issue #2599454 by rakesh.gectcr, metzlerd, snehi, jhodgdon: Document Missing HTML Render Elements

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

@@ -16,6 +16,24 @@
 /**
  * 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 @@
 /**
  * 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 @@
  * 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 @@
 /**
  * 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 @@
 /**
  * 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 @@
 /**
  * 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/StatusMessages.php

@@ -10,6 +10,15 @@
 /**
  * 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\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")
  */