Changeset 51949

Timestamp:

10/29/2021 03:33:18 PM (3 years ago)

Author:

johnbillion

Message:

Site Health: Correct and improve the documentation for the debug_information hook.

This corrects the structure of the documentation so it accurately reflects the array elements contained within.

See #53399.

File:

• trunk/src/wp-admin/includes/class-wp-debug-data.php (modified) (3 diffs)

trunk/src/wp-admin/includes/class-wp-debug-data.php

@@ -1409 +1409 @@
 
         /**
-         * Add or modify the debug information.
+         * Add to or modify the debug information shown on the Tools -> Site Health -> Info screen.
          *
          * Plugin or themes may wish to introduce their own debug information without creating additional admin pages
@@ -1418 +1418 @@
          * for the copied data.
          *
-         * All strings are expected to be plain text except $description that can contain inline HTML tags (see below).
+         * All strings are expected to be plain text except `$description` that can contain inline HTML tags (see below).
          *
          * @since 5.2.0
@@ -1425 +1425 @@
          *     The debug information to be added to the core information page.
          *
-         *     This is an associative multi-dimensional array, up to three levels deep. The topmost array holds the sections.
-         *     Each section has a `$fields` associative array (see below), and each `$value` in `$fields` can be
-         *     another associative array of name/value pairs when there is more structured data to display.
+         *     This is an associative multi-dimensional array, up to three levels deep. The topmost array holds the sections, keyed by section ID.
          *
-         *     @type string  $label        The title for this section of the debug output.
-         *     @type string  $description  Optional. A description for your information section which may contain basic HTML
-         *                                 markup, inline tags only as it is outputted in a paragraph.
-         *     @type boolean $show_count   Optional. If set to `true` the amount of fields will be included in the title for
-         *                                 this section.
-         *     @type boolean $private      Optional. If set to `true` the section and all associated fields will be excluded
-         *                                 from the copied data.
-         *     @type array   $fields {
-         *         An associative array containing the data to be displayed.
+         *     @type array ...$0 {
+         *         Each section has a `$fields` associative array (see below), and each `$value` in `$fields` can be
+         *         another associative array of name/value pairs when there is more structured data to display.
          *
-         *         @type string  $label    The label for this piece of information.
-         *         @type string  $value    The output that is displayed for this field. Text should be translated. Can be
-         *                                 an associative array that is displayed as name/value pairs.
-         *         @type string  $debug    Optional. The output that is used for this field when the user copies the data.
-         *                                 It should be more concise and not translated. If not set, the content of `$value` is used.
-         *                                 Note that the array keys are used as labels for the copied data.
-         *         @type boolean $private  Optional. If set to `true` the field will not be included in the copied data
-         *                                 allowing you to show, for example, API keys here.
+         *         @type string $label       Required. The title for this section of the debug output.
+         *         @type string $description Optional. A description for your information section which may contain basic HTML
+         *                                   markup, inline tags only as it is outputted in a paragraph.
+         *         @type bool   $show_count  Optional. If set to `true` the amount of fields will be included in the title for
+         *                                   this section.
+         *         @type bool   $private     Optional. If set to `true` the section and all associated fields will be excluded
+         *                                   from the copied data. Default false.
+         *         @type array  $fields {
+         *             Required. An associative array containing the fields to be displayed in the section, keyed by field ID.
+         *
+         *             @type array ...$0 {
+         *                 An associative array containing the data to be displayed for the field.
+         *
+         *                 @type string $label    Required. The label for this piece of information.
+         *                 @type mixed  $value    Required. The output that is displayed for this field. Text should be translated. Can be
+         *                                        an associative array that is displayed as name/value pairs.
+         *                                        Accepted types: `string|int|float|(string|int|float)[]`.
+         *                 @type string $debug    Optional. The output that is used for this field when the user copies the data.
+         *                                        It should be more concise and not translated. If not set, the content of `$value` is used.
+         *                                        Note that the array keys are used as labels for the copied data.
+         *                 @type bool   $private  Optional. If set to `true` the field will not be included in the copied data
+         *                                        allowing you to show, for example, API keys here. Default false.
+         *             }
+         *         }
          *     }
          * }