Changeset 47384

Timestamp:

02/27/2020 08:07:31 PM (6 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() ) {