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

Timestamp:

10/29/2021 03:33:18 PM (5 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.
+                 *             }
+                 *         }
                  *     }
                  * }