Adding documentation for wp.customize properties

[shramee]

Adding documentation for...

• wp.customize.control
• wp.customize.section
• wp.customize.panel

Along with examples for usage.

[shramee]

Patch for docs

[westonruter]

Thanks. I wouldn't mention _values as it is private. The items in the collection should only be accessed via the methods on Values like each().

Also, instead of @return {object|undefined} these should have @returns {wp.customize.Section|undefined} according to the various types.

Also a key example to include is how to use the deferred pattern, for example:

wp.customize.section( 'title_tagline', function( section ) { section.expand(); } )

The deferred pattern is preferred since it ensures there is no JS error in the case of something not being registered.

[shramee]

Aye, Agree @westonruter,

Adding a new patch ;)

[shramee]

Second patch for docs

[shramee]

@westonruter Thanks a lot, I am using this in one of my plugin (will be live on wp.org soon).
Passing a deferred (anonymous) function would make my plugin more robust :)

PFA 39930-1.patch

[jbpaul17]

Per yesterday's bug scrub, we're going to punt this to 4.8.1.

[jbpaul17]

As this is a documentation update, we'll switch this from an enhancement to a task ticket type.

[westonruter]

In 41799:

Customize: Add jsdoc for api.panel, api.section, api.control, and api.notifications collections.

Props shramee, westonruter.
Fixes #39930.

[westonruter]

In 63455:

Customize: Correct the JSDoc for the controls API.

Many of the types named nothing that resolves. The four deferred getters referred to their callback typedefs without a namespace, the promise they return was spelled jQuery.promise, which is neither the capitalization the namespace is declared under nor the name of a type, and jQuery events were typed as plain objects.

Two blocks documented the wrong thing outright. ThemesPanel lent its prototype to a name misspelled without the second e, so its methods were attached to a namespace that exists nowhere else, and getInitialHeaderImage() carried the return of the method beside it, describing a set of cropper options where its own summary already said it returns a model.

Parameters the code treats as optional are marked as such.

Developed as subset of ​https://github.com/WordPress/wordpress-develop/pull/10743.
Follow-up to r41799, r48650, r63454.

Props westonruter, afercia.
See #39671, #39930, #40831, #64662, #66033.