Ticket #39930: 39930-1.patch

src/wp-admin/js/customize-controls.js

@@ -3381 +3381 @@
         // Change objects contained within the main customize object to Settings.
         api.defaultConstructor = api.Setting;
 
-        // Create the collections for Controls, Sections and Panels.
+        /**
+         * Get instance of control by ID
+         * Use wp.customize.control.each( function(){ ... } ) to loop through each control registered in customizer
+         *
+         * @param {string} ID of control
+         * @param {function} Called if control with ID is found, control instance passed as first parameter
+         * @returns {wp.customize.Control|undefined} Control instance or undefined
+         *
+         * @example wp.customize.control('background_color') Getting `background_color` control instance
+         * @example wp.customize.control('background_color').setting.get() Getting `background_color` value
+         * @example wp.customize.control('background_color', function( control ){ control.setting.set('#f00') } ) Setting `background_color` to red
+         */
         api.control = new api.Values({ defaultConstructor: api.Control });
+
+        /**
+         * Get instance of section by ID
+         * Use wp.customize.section.each( function(){ ... } ) to loop through each section registered in customizer
+         *
+         * @param {string} ID of section
+         * @param {function} Called if section with ID is found, section instance passed as first parameter
+         * @returns {wp.customize.Section|undefined} Section instance or undefined
+         *
+         * @example wp.customize.section('title_tagline') Getting `title_tagline` section instance
+         * @example wp.customize.section('title_tagline', function( section ){ section.expand() } ) Expand (enter) `title_tagline` section
+         */
         api.section = new api.Values({ defaultConstructor: api.Section });
+
+        /**
+         * Get instance of panel by ID
+         * Use wp.customize.panel.each( function(){ ... } ) to loop through each panel registered in customizer
+         *
+         * @param {string} ID of panel
+         * @param {function} Called if panel with ID is found, panel instance passed as first parameter
+         * @returns {wp.customize.Panel|undefined} Panel instance or undefined
+         *
+         * @example wp.customize.panel('nav_menus') Getting nav_menus panel instance
+         * @example wp.customize.panel('nav_menus', function( panel ){ panel.expand() } ) Expand (enter) nav_menus panel
+         */
         api.panel = new api.Values({ defaultConstructor: api.Panel });
 
         /**