Issue #2603818 by jhodgdon, beejeebus, blackra: Add defgroups for listing page headers for api.drupal.org

core/core.api.php

@@ -692,7 +692,7 @@
  * "service" (such as accessing the database, sending email, or translating user
  * interface text) is defined (given a name and an interface or at least a
  * class that defines the methods that may be called), and a default class is
- * defined to provide the service. These two steps must be done together, and
+ * designated to provide the service. These two steps must be done together, and
  * can be done by Drupal Core or a module. Other modules can then define
  * alternative classes to provide the same services, overriding the default
  * classes. Classes and functions that need to use the service should always
@@ -843,6 +843,32 @@
  * @}
  */
 
+/**
+ * @defgroup listing_page_service Page header for Services page
+ * @{
+ * Introduction to services
+ *
+ * A "service" (such as accessing the database, sending email, or translating
+ * user interface text) can be defined by a module or Drupal core. Defining a
+ * service means giving it a name and designating a default class to provide the
+ * service; ideally, there should also be an interface that defines the methods
+ * that may be called. Services are collected into the Dependency Injection
+ * Container, and can be overridden to use different classes or different
+ * instantiation by modules. See the
+ * @link container Services and Dependency Injection Container topic @endlink
+ * for details.
+ *
+ * Some services have tags, which are defined in the service definition. Tags
+ * are used to define a group of related services, or to specify some aspect of
+ * how the service behaves. See the
+ * @link service_tag Service Tags topic @endlink for more information.
+ *
+ * @see container
+ * @see service_tag
+ *
+ * @}
+ */
+
 /**
  * @defgroup typed_data Typed Data API
  * @{
@@ -1441,6 +1467,38 @@
  * @}
  */
 
+/**
+ * @defgroup listing_page_class Page header for Classes page
+ * @{
+ * Introduction to classes
+ *
+ * A lot of the PHP code in Drupal is object oriented (OO), making use of
+ * @link http://php.net/manual/language.oop5.php PHP classes, interfaces, and traits. @endlink
+ * See the
+ * @link oo_conventions Objected-oriented programming conventions @endlink
+ * for more information.
+ *
+ * @see oo_conventions
+ *
+ * @}
+ */
+
+/**
+ * @defgroup listing_page_namespace Page header for Namespaces page
+ * @{
+ * Introduction to namespaces
+ *
+ * PHP classes, interfaces, and traits in Drupal are
+ * @link http://php.net/manual/en/language.namespaces.rationale.php namespaced. @endlink
+ * See the
+ * @link oo_conventions Objected-oriented programming conventions @endlink
+ * for more information.
+ *
+ * @see oo_conventions
+ *
+ * @}
+ */
+
 /**
  * @defgroup best_practices Best practices for developers
  * @{
@@ -1667,16 +1725,13 @@
  *     _form: '\Drupal\mymodule\Form\ExampleForm'
  * @endcode
  *
- * The $form argument to form-related functions is a structured array containing
- * the elements and properties of the form. For information on the array
- * components and format, and more detailed explanations of the Form API
- * workflow, see the
- * @link forms_api_reference.html Form API reference @endlink
- * and the
+ * The $form argument to form-related functions is a specialized render array
+ * containing the elements and properties of the form. For more about render
+ * arrays, see the @link theme_render Render API topic. @endlink For more
+ * detailed explanations of the Form API workflow, see the
  * @link https://www.drupal.org/node/2117411 Form API documentation section. @endlink
- * In addition, there is a set of Form API tutorials in
- * @link form_example_tutorial.inc the Form Example Tutorial @endlink which
- * provide basics all the way up through multistep forms.
+ * In addition, there is a set of Form API tutorials in the
+ * @link https://www.drupal.org/project/examples Examples for Developers project. @endlink
  *
  * In the form builder, validation, submission, and other form methods,
  * $form_state is the primary influence on the processing of the form and is

core/lib/Drupal/Core/Form/FormState.php

@@ -212,9 +212,8 @@ class FormState implements FormStateInterface {
    *
    * The validation functions and submit functions use this array for nearly all
    * their decision making. (Note that #tree determines whether the values are a
-   * flat array or an array whose structure parallels the $form array. See the
-   * @link forms_api_reference.html Form API reference @endlink for more
-   * information.)
+   * flat array or an array whose structure parallels the $form array. See
+   * \Drupal\Core\Render\Element\FormElement for more information.)
    *
    * This property is uncacheable.
    *

core/lib/Drupal/Core/Form/form.api.php

@@ -194,7 +194,8 @@ function hook_ajax_render_alter(array &$data) {
  *
  * @see hook_form_BASE_FORM_ID_alter()
  * @see hook_form_FORM_ID_alter()
- * @see forms_api_reference.html
+ *
+ * @ingroup form_api
  */
 function hook_form_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {
   if (isset($form['type']) && $form['type']['#value'] . '_node_settings' == $form_id) {
@@ -237,7 +238,8 @@ function hook_form_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_stat
  * @see hook_form_alter()
  * @see hook_form_BASE_FORM_ID_alter()
  * @see \Drupal\Core\Form\FormBuilderInterface::prepareForm()
- * @see forms_api_reference.html
+ *
+ * @ingroup form_api
  */
 function hook_form_FORM_ID_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {
   // Modification for the form with the given form ID goes here. For example, if
@@ -286,6 +288,8 @@ function hook_form_FORM_ID_alter(&$form, \Drupal\Core\Form\FormStateInterface $f
  * @see hook_form_alter()
  * @see hook_form_FORM_ID_alter()
  * @see \Drupal\Core\Form\FormBuilderInterface::prepareForm()
+ *
+ * @ingroup form_api
  */
 function hook_form_BASE_FORM_ID_alter(&$form, \Drupal\Core\Form\FormStateInterface $form_state, $form_id) {
   // Modification for the form with the given BASE_FORM_ID goes here. For

core/lib/Drupal/Core/Plugin/PluginFormInterface.php

@@ -27,8 +27,7 @@ interface PluginFormInterface {
    * callback and build the rest of the form in the callback. By the time the
    * callback is executed, the element's #parents and #array_parents properties
    * will have been set by the form API. For more documentation on #parents and
-   * #array_parents, see
-   * https://api.drupal.org/api/drupal/developer!topics!forms_api_reference.html/8.
+   * #array_parents, see \Drupal\Core\Render\Element\FormElement.
    *
    * @param array $form
    *   An associative array containing the initial structure of the plugin form.

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

@@ -472,6 +472,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
  * @{

core/modules/field/field.api.php

@@ -106,9 +106,9 @@ function hook_field_storage_config_update_forbid(\Drupal\field\FieldStorageConfi
  * subclassing \Drupal\Core\Field\WidgetBase). Widget plugins need to be in the
  * namespace \Drupal\{your_module}\Plugin\Field\FieldWidget.
  *
- * Widgets are @link forms_api_reference.html Form API @endlink
- * elements with additional processing capabilities. The methods of the
- * WidgetInterface object are typically called by respective methods in the
+ * Widgets are @link form_api Form API @endlink elements with additional
+ * processing capabilities. The methods of the WidgetInterface object are
+ * typically called by respective methods in the
  * \Drupal\Core\Entity\Entity\EntityFormDisplay class.
  *
  * @see field

core/modules/system/templates/container.html.twig

@@ -5,8 +5,10 @@
  *
  * Used for grouped form items. Can also be used as a theme wrapper for any
  * renderable element, to surround it with a <div> and HTML attributes.
- * See the @link forms_api_reference.html Form API reference @endlink for more
- * information on the #theme_wrappers render array property.
+ * See \Drupal\Core\Render\Element\RenderElement for more
+ * information on the #theme_wrappers render array property, and
+ * \Drupal\Core\Render\Element\container for usage of the container render
+ * element.
  *
  * Available variables:
  * - attributes: HTML attributes for the containing element.

core/themes/classy/templates/form/container.html.twig

@@ -5,8 +5,10 @@
  *
  * Used for grouped form items. Can also be used as a theme wrapper for any
  * renderable element, to surround it with a <div> and HTML attributes.
- * See the @link forms_api_reference.html Form API reference @endlink for more
- * information on the #theme_wrappers render array property.
+ * See \Drupal\Core\Render\Element\RenderElement for more
+ * information on the #theme_wrappers render array property, and
+ * \Drupal\Core\Render\Element\container for usage of the container render
+ * element.
  *
  * Available variables:
  * - attributes: HTML attributes for the containing element.

core/themes/stable/templates/form/container.html.twig

@@ -5,8 +5,10 @@
  *
  * Used for grouped form items. Can also be used as a theme wrapper for any
  * renderable element, to surround it with a <div> and HTML attributes.
- * See the @link forms_api_reference.html Form API reference @endlink for more
- * information on the #theme_wrappers render array property.
+ * See \Drupal\Core\Render\Element\RenderElement for more
+ * information on the #theme_wrappers render array property, and
+ * \Drupal\Core\Render\Element\container for usage of the container render
+ * element.
  *
  * Available variables:
  * - attributes: HTML attributes for the containing element.