Changeset 56414

Timestamp:

08/18/2023 05:27:16 PM (14 months ago)

Author:

johnbillion

Message:

Docs: Miscellaneous docblock corrections and improvements.

See #58833

Location:

trunk/src

Files:

• wp-admin/includes/plugin.php (modified) (2 diffs)
• wp-admin/includes/schema.php (modified) (1 diff)
• wp-includes/block-supports/utils.php (modified) (1 diff)
• wp-includes/block-template-utils.php (modified) (1 diff)
• wp-includes/class-wp-block-type.php (modified) (1 diff)
• wp-includes/class-wp-navigation-fallback.php (modified) (1 diff)
• wp-includes/class-wp-theme-json.php (modified) (1 diff)
• wp-includes/cron.php (modified) (10 diffs)
• wp-includes/functions.php (modified) (1 diff)
• wp-includes/functions.wp-scripts.php (modified) (4 diffs)
• wp-includes/l10n.php (modified) (1 diff)
• wp-includes/post.php (modified) (1 diff)
• wp-includes/theme.php (modified) (1 diff)

trunk/src/wp-admin/includes/plugin.php

@@ -855 +855 @@
  *                                      Default false.
  * @param bool            $silent       Prevent calling activation hooks. Default false.
- * @return bool|WP_Error True when finished or WP_Error if there were errors during a plugin activation.
+ * @return true|WP_Error True when finished or WP_Error if there were errors during a plugin activation.
  */
 function activate_plugins( $plugins, $redirect = '', $network_wide = false, $silent = false ) {
@@ -2441 +2441 @@
  * @param string $plugin   Single plugin to resume.
  * @param string $redirect Optional. URL to redirect to. Default empty string.
- * @return bool|WP_Error True on success, false if `$plugin` was not paused,
+ * @return true|WP_Error True on success, false if `$plugin` was not paused,
  *                       `WP_Error` on failure.
  */

trunk/src/wp-admin/includes/schema.php

@@ -980 +980 @@
  * @param bool   $subdomain_install Optional. Whether the network is a subdomain installation or a subdirectory installation.
  *                                  Default false, meaning the network is a subdirectory installation.
- * @return bool|WP_Error True on success, or WP_Error on warning (with the installation otherwise successful,
+ * @return true|WP_Error True on success, or WP_Error on warning (with the installation otherwise successful,
  *                       so the error code must be checked) or failure.
  */

trunk/src/wp-includes/block-supports/utils.php

@@ -19 +19 @@
  * @param string        $feature     Optional name of individual feature to check.
  *
- * @return boolean Whether to serialize block support styles & classes.
+ * @return bool Whether to serialize block support styles & classes.
  */
 function wp_should_skip_block_supports_serialization( $block_type, $feature_set, $feature = null ) {

trunk/src/wp-includes/block-template-utils.php

@@ -309 +309 @@
  *     Arguments to retrieve templates. Optional, empty by default.
  *
- *     @type array  $slug__in     List of slugs to include.
- *     @type array  $slug__not_in List of slugs to skip.
- *     @type string $area         A 'wp_template_part_area' taxonomy value to filter by (for 'wp_template_part' template type only).
- *     @type string $post_type    Post type to get the templates for.
+ *     @type string[] $slug__in     List of slugs to include.
+ *     @type string[] $slug__not_in List of slugs to skip.
+ *     @type string   $area         A 'wp_template_part_area' taxonomy value to filter by (for 'wp_template_part' template type only).
+ *     @type string   $post_type    Post type to get the templates for.
  * }
  *

trunk/src/wp-includes/class-wp-block-type.php

@@ -334 +334 @@
      * @param string $name Deprecated property name.
      *
-     * @return boolean Returns true when for the new property the first item in the array exists,
-     *                     or false otherwise.
+     * @return bool Returns true when for the new property the first item in the array exists,
+     *              or false otherwise.
      */
     public function __isset( $name ) {

trunk/src/wp-includes/class-wp-navigation-fallback.php

@@ -32 +32 @@
          * @since 6.3.0
          *
-         * @param bool Whether to create a fallback navigation menu. Default true.
+         * @param bool $create Whether to create a fallback navigation menu. Default true.
          */
         $should_create_fallback = apply_filters( 'wp_navigation_should_create_fallback', true );

trunk/src/wp-includes/class-wp-theme-json.php

@@ -2686 +2686 @@
      * @param array      $path       Path to inspect.
      * @param bool|array $override   Data to compute whether to override the preset.
-     * @return boolean
+     * @return bool
      */
     protected static function should_override_preset( $theme_json, $path, $override ) {

trunk/src/wp-includes/cron.php

@@ -58 +58 @@
 
     /**
-     * Filter to preflight or hijack scheduling an event.
+     * Filter to override scheduling an event.
      *
      * Returning a non-null value will short-circuit adding the event to the
@@ -377 +377 @@
 
     /**
-     * Filter to preflight or hijack rescheduling of a recurring event.
+     * Filter to override rescheduling of a recurring event.
      *
      * Returning a non-null value will short-circuit the normal rescheduling
@@ -474 +474 @@
 
     /**
-     * Filter to preflight or hijack unscheduling of events.
+     * Filter to override unscheduling of events.
      *
      * Returning a non-null value will short-circuit the normal unscheduling
@@ -527 +527 @@
  * Unschedules all events attached to the hook with the specified arguments.
  *
- * Warning: This function may return Boolean FALSE, but may also return a non-Boolean
- * value which evaluates to FALSE. For information about casting to booleans see the
+ * Warning: This function may return boolean false, but may also return a non-boolean
+ * value which evaluates to false. For information about casting to booleans see the
  * {@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use
  * the `===` operator for testing the return value of this function.
@@ -564 +564 @@
 
     /**
-     * Filter to preflight or hijack clearing a scheduled hook.
+     * Filter to override clearing a scheduled hook.
      *
      * Returning a non-null value will short-circuit the normal unscheduling
@@ -638 +638 @@
  * Can be useful for plugins when deactivating to clean up the cron queue.
  *
- * Warning: This function may return Boolean FALSE, but may also return a non-Boolean
- * value which evaluates to FALSE. For information about casting to booleans see the
+ * Warning: This function may return boolean false, but may also return a non-boolean
+ * value which evaluates to false. For information about casting to booleans see the
  * {@link https://www.php.net/manual/en/language.types.boolean.php PHP documentation}. Use
  * the `===` operator for testing the return value of this function.
@@ -654 +654 @@
 function wp_unschedule_hook( $hook, $wp_error = false ) {
     /**
-     * Filter to preflight or hijack clearing all events attached to the hook.
+     * Filter to override clearing all events attached to the hook.
      *
      * Returning a non-null value will short-circuit the normal unscheduling
@@ -750 +750 @@
 function wp_get_scheduled_event( $hook, $args = array(), $timestamp = null ) {
     /**
-     * Filter to preflight or hijack retrieving a scheduled event.
+     * Filter to override retrieving a scheduled event.
      *
      * Returning a non-null value will short-circuit the normal process,
@@ -966 +966 @@
  * @since 5.7.0 Functionality moved to _wp_cron() to which this becomes a wrapper.
  *
- * @return bool|int|void On success an integer indicating number of events spawned (0 indicates no
- *                       events needed to be spawned), false if spawning fails for one or more events or
- *                       void if the function registered _wp_cron() to run on the action.
+ * @return false|int|void On success an integer indicating number of events spawned (0 indicates no
+ *                        events needed to be spawned), false if spawning fails for one or more events or
+ *                        void if the function registered _wp_cron() to run on the action.
  */
 function wp_cron() {
@@ -1161 +1161 @@
 function wp_get_ready_cron_jobs() {
     /**
-     * Filter to preflight or hijack retrieving ready cron jobs.
+     * Filter to override retrieving ready cron jobs.
      *
      * Returning an array will short-circuit the normal retrieval of ready

trunk/src/wp-includes/functions.php

@@ -8601 +8601 @@
  * @param int|float $expected  The expected value.
  * @param int|float $actual    The actual number.
- * @param int|float $precision The allowed variation.
+ * @param int|float $precision Optional. The allowed variation. Default 1.
  * @return bool Whether the numbers match within the specified precision.
  */

trunk/src/wp-includes/functions.wp-scripts.php

@@ -74 +74 @@
  * Called by admin-header.php and {@see 'wp_head'} hook. Since it is called by wp_head on every page load,
  * the function does not instantiate the WP_Scripts object unless script names are explicitly passed.
- * Makes use of already-instantiated $wp_scripts global if present. Use provided {@see 'wp_print_scripts'}
+ * Makes use of already-instantiated `$wp_scripts` global if present. Use provided {@see 'wp_print_scripts'}
  * hook to register/enqueue new scripts.
  *
@@ -114 +114 @@
  *
  * Code will only be added if the script is already in the queue.
- * Accepts a string $data containing the Code. If two or more code blocks
- * are added to the same script $handle, they will be printed in the order
+ * Accepts a string `$data` containing the code. If two or more code blocks
+ * are added to the same script `$handle`, they will be printed in the order
  * they were added, i.e. the latter added code can redeclare the previous.
  *
@@ -202 +202 @@
  * Works only if the script has already been registered.
  *
- * Accepts an associative array $l10n and creates a JavaScript object:
- *
- *     "$object_name" = {
+ * Accepts an associative array `$l10n` and creates a JavaScript object:
+ *
+ *     "$object_name": {
  *         key: value,
  *         key: value,
@@ -338 +338 @@
  * Enqueues a script.
  *
- * Registers the script if $src provided (does NOT overwrite), and enqueues it.
+ * Registers the script if `$src` provided (does NOT overwrite), and enqueues it.
  *
  * @see WP_Dependencies::add()

trunk/src/wp-includes/l10n.php

@@ -1518 +1518 @@
  *     @type string   $id                           ID attribute of the select element. Default 'locale'.
  *     @type string   $name                         Name attribute of the select element. Default 'locale'.
- *     @type array    $languages                    List of installed languages, contain only the locales.
+ *     @type string[] $languages                    List of installed languages, contain only the locales.
  *                                                  Default empty array.
  *     @type array    $translations                 List of available translations. Default result of

trunk/src/wp-includes/post.php

@@ -4975 +4975 @@
  * @since 5.7.0
  *
- * @param string $post_date     The date in mysql format.
- * @param string $post_date_gmt The GMT date in mysql format.
+ * @param string $post_date     The date in mysql format (`Y-m-d H:i:s`).
+ * @param string $post_date_gmt The GMT date in mysql format (`Y-m-d H:i:s`).
  * @return string|false A valid Gregorian-calendar date string, or false on failure.
  */

trunk/src/wp-includes/theme.php

@@ -4269 +4269 @@
  * @since 5.9.0
  *
- * @return boolean Whether the active theme is a block-based theme or not.
+ * @return bool Whether the active theme is a block-based theme or not.
  */
 function wp_is_block_theme() {