Ticket #39930: 39930.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
+         * All controls' instances in _values property (object) with control ID as property
+         *
+         * @param {string} id ID of control
+         * @return {object|undefined} Control object or undefined
+         *
+         * @example wp.customize.control('background_color') Getting `background_color` control object
+         * @example wp.customize.control('background_color').setting.get() Getting `background_color` value
+         * @example wp.customize.control('background_color').setting.set( '#f00' ) Setting `background_color` to red
+         */
         api.control = new api.Values({ defaultConstructor: api.Control });
+
+        /**
+         * Get instance of section by ID
+         * All controls' instances in _values property (object) with control ID as property
+         *
+         * @param {string} ID of section
+         * @return {object|undefined} Section object or undefined
+         *
+         * @example wp.customize.section('title_tagline') Getting `title_tagline` section object
+         * @example wp.customize.section('title_tagline').expand() Expanding (Entering) `title_tagline` section
+         */
         api.section = new api.Values({ defaultConstructor: api.Section });
+
+        /**
+         * Get instance of panel by ID
+         * All panels' instances in _values property (object) with panel ID as property
+         *
+         * @param {string} id ID of panel
+         * @return {object|undefined} Panel object or undefined
+         *
+         * @example wp.customize.panel('nav_menus') Getting nav_menus panel object
+         * @example wp.customize.panel('nav_menus').expand() Expand (enter) nav_menus panel
+         */
         api.panel = new api.Values({ defaultConstructor: api.Panel });
 
         /**