Changeset 47384

Timestamp:

02/27/2020 08:07:31 PM (7 years ago)

Author:

SergeyBiryukov

Message:

Docs: Add a reference to WP_Customize_Setting::__construct() for information on accepted arguments in WP_Customize_Manager::add_setting().

Synchronize the documentation between two places, use WP_Customize_Setting::__construct() as the canonical source.

Props tmanoilov, marekdedic.
Fixes #48347.

Location:

trunk/src/wp-includes

Files:

• class-wp-customize-control.php (modified) (1 diff)
• class-wp-customize-manager.php (modified) (6 diffs)
• class-wp-customize-setting.php (modified) (1 diff)

trunk/src/wp-includes/class-wp-customize-control.php

@@ -175 +175 @@
          * @param string               $id      Control ID.
          * @param array                $args    {
-         *     Optional. Arguments to override class property defaults.
+         *     Optional. Array of properties for the new Control object. Default empty array.
          *
          *     @type int                  $instance_number Order in which this instance was created in relation

trunk/src/wp-includes/class-wp-customize-manager.php

@@ -3161 +3161 @@
          * @param int      $user_id The user ID.
          * @param array    $args    Adds the context to the cap. Typically the object ID.
-         * @return array   Capabilities.
+         * @return array Capabilities.
          */
         public function grant_edit_post_capability_for_changeset( $caps, $cap, $user_id, $args ) {
@@ -3357 +3357 @@
          * @param WP_Post $last_revision    The last revision post object.
          * @param WP_Post $post             The post object.
-         *
          * @return bool Whether a revision should be made.
          */
@@ -3681 +3680 @@
          * @since 4.5.0 Return added WP_Customize_Setting instance.
          *
+         * @see WP_Customize_Setting::__construct()
          * @link https://developer.wordpress.org/themes/customize-api
          *
          * @param WP_Customize_Setting|string $id   Customize Setting object, or ID.
-         * @param array                       $args {
-         *  Optional. Array of properties for the new WP_Customize_Setting. Default empty array.
-         *
-         *  @type string       $type                  Type of the setting. Default 'theme_mod'.
-         *  @type string       $capability            Capability required for the setting. Default 'edit_theme_options'
-         *  @type string|array $theme_supports        Theme features required to support the panel. Default is none.
-         *  @type string       $default               Default value for the setting. Default is empty string.
-         *  @type string       $transport             Options for rendering the live preview of changes in Customizer.
-         *                                            Using 'refresh' makes the change visible by reloading the whole preview.
-         *                                            Using 'postMessage' allows a custom JavaScript to handle live changes.
-         *                                            Default is 'refresh'.
-         *  @type callable     $validate_callback     Server-side validation callback for the setting's value.
-         *  @type callable     $sanitize_callback     Callback to filter a Customize setting value in un-slashed form.
-         *  @type callable     $sanitize_js_callback  Callback to convert a Customize PHP setting value to a value that is
-         *                                            JSON serializable.
-         *  @type bool         $dirty                 Whether or not the setting is initially dirty when created.
-         * }
-         * @return WP_Customize_Setting             The instance of the setting that was added.
+         * @param array                       $args Optional. Array of properties for the new Setting object.
+         *                                          See WP_Customize_Setting::__construct() for information
+         *                                          on accepted arguments. Default empty array.
+         * @return WP_Customize_Setting The instance of the setting that was added.
          */
         public function add_setting( $id, $args = array() ) {
@@ -3828 +3814 @@
          *  @type callable     $active_callback       Active callback.
          * }
-         * @return WP_Customize_Panel             The instance of the panel that was added.
+         * @return WP_Customize_Panel The instance of the panel that was added.
          */
         public function add_panel( $id, $args = array() ) {
@@ -3926 +3912 @@
          *  @type bool         $description_hidden    Hide the description behind a help icon, instead of inline above the first control. Default false.
          * }
-         * @return WP_Customize_Section             The instance of the section that was added.
+         * @return WP_Customize_Section The instance of the section that was added.
          */
         public function add_section( $id, $args = array() ) {
@@ -4005 +3991 @@
          *                                          See WP_Customize_Control::__construct() for information
          *                                          on accepted arguments. Default empty array.
-         * @return WP_Customize_Control             The instance of the control that was added.
+         * @return WP_Customize_Control The instance of the control that was added.
          */
         public function add_control( $id, $args = array() ) {

trunk/src/wp-includes/class-wp-customize-setting.php

@@ -157 +157 @@
          * @param string               $id      A specific ID of the setting.
          *                                      Can be a theme mod or option name.
-         * @param array                $args    Setting arguments.
+         * @param array                $args    {
+         *  Optional. Array of properties for the new Setting object. Default empty array.
+         *
+         *  @type string       $type                  Type of the setting. Default 'theme_mod'.
+         *  @type string       $capability            Capability required for the setting. Default 'edit_theme_options'
+         *  @type string|array $theme_supports        Theme features required to support the panel. Default is none.
+         *  @type string       $default               Default value for the setting. Default is empty string.
+         *  @type string       $transport             Options for rendering the live preview of changes in Customizer.
+         *                                            Using 'refresh' makes the change visible by reloading the whole preview.
+         *                                            Using 'postMessage' allows a custom JavaScript to handle live changes.
+         *                                            Default is 'refresh'.
+         *  @type callable     $validate_callback     Server-side validation callback for the setting's value.
+         *  @type callable     $sanitize_callback     Callback to filter a Customize setting value in un-slashed form.
+         *  @type callable     $sanitize_js_callback  Callback to convert a Customize PHP setting value to a value that is
+         *                                            JSON serializable.
+         *  @type bool         $dirty                 Whether or not the setting is initially dirty when created.
+         * }
          */
         public function __construct( $manager, $id, $args = array() ) {