Improve inline documentation of widgets API

[ericlewis]

There's a few places we need more documentation, and the existing documentation is misleading, especially in defining instances of widgets vs widget classes.

[DrewAPicture]

It would be great if you could add the @since versions on the methods you're adding docs to. If we're going to add docs where none previously were, I'd like to be as complete as possible so as not to create additional future work.

[ericlewis]

Although I understand that it would be nice to get @since tags, I disagree with the approach that docs is an all-or-no-commit venture. More documentation is better than no documentation, and improved documentation is better than existing documentation. If someone wants to update just the description of a single parameter to a function, I think they should be able to make that contribution without any more barrier to contribution.

Here, I needed to figure out some widgets internals for my day job, so I added the documentation that I needed to get me through, and hope(/know) it will benefit other WordPress developers. If I'm responsible for adding @since tags whenever I touch any documentation, I'm not going to contribute as much.

[jazzs3quence]

Cleaned up some comments and added @since versions to the docblocks added in the previous patch

[DrewAPicture]

Looks like [30382] missed the ticket. That covered the changes submitted by @ericlewis and @jazzs3quence.

[blobaugh]

Adding documentation to wp_list_widget_controls_dynamic_sidebar

[blobaugh]

Added documentation to next_widget_id_number

[blobaugh]

Added array parameter documentation to wp_widget_control

[jazzs3quence]

Adds some more @since tags

[DrewAPicture]

Hi Ben, thanks for the patches.

Please refer to the ​Parameters that are arrays section of the standard for a refresher on the syntax for hash notations. The example provided there is meant to be used as an exact guide for what's expected.

30315.2.diff​:

• The inner hash notation should only be indented four spaces
• Descriptions including the hash description should always end with a period. They're very literally sentences

30315.3.diff​:

• There should be a blank line between the summary and description
• Parameter and return descriptions should always end with a period
• The return type should be int and there should be a description (with a period)

30315.4.diff​:

• The hash notation should begin with a description, followed by a blank line, followed by the @type lines
• Each @type line should only be indented four spaces
• The types and descriptions should be left-aligned with each other
• The descriptions should mention what type of values are accepted and what the defaults are.

[DrewAPicture]

In 30691:

Improve inline documentation for four methods in WP_Widget: get_field_id(), display_callback(), update_callback(), and form_callback().

Props jazzs3quence for the initial patch.
See #30315.

[DrewAPicture]

In 30773:

Introduce documentation for the $id_base, $name, $widget_options, $control_options, $number, $id, and $updated properties in `WP_Widget'.

See #30315.

[DrewAPicture]

In 30774:

Introduce documentation for three methods in WP_Widget_Factory: register(), unregister(), _register_widgets().

See #30315.

[DrewAPicture]

In 30776:

Flesh out information in the DocBlock for wp_register_sidebar_widget().

Includes:

• Documenting the $options parameter in hash notation style
• Converting @uses tags to @global
• Various backtick-escaping.

See #30315.

[DrewAPicture]

In 30778:

Flesh out and fix formatting in the DocBlock for wp_register_widget_control().

Includes:

• Added todos for documenting $options in the hash notation style
• Backtick-escaping and general formatting

See #30315.

[DrewAPicture]

In 30779:

Fix formatting in the DocBlock for wp_get_sidebars_widgets().

See #30315.