WordPress.org

Make WordPress Core

Opened 5 years ago

Closed 4 years ago

#30315 closed defect (bug) (fixed)

Improve inline documentation of widgets API

Reported by: ericlewis Owned by:
Milestone: 4.1 Priority: normal
Severity: normal Version: 2.8
Component: Widgets Keywords: has-patch
Focuses: docs Cc:
PR Number:

Description

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

Attachments (6)

30315.diff (4.3 KB) - added by ericlewis 5 years ago.
30315.1.diff (6.3 KB) - added by jazzs3quence 5 years ago.
Cleaned up some comments and added @since versions to the docblocks added in the previous patch
30315.2.diff (1.0 KB) - added by blobaugh 5 years ago.
Adding documentation to wp_list_widget_controls_dynamic_sidebar
30315.3.diff (798 bytes) - added by blobaugh 5 years ago.
Added documentation to next_widget_id_number
30315.4.diff (1.1 KB) - added by blobaugh 5 years ago.
Added array parameter documentation to wp_widget_control
30315.5.diff (1.1 KB) - added by jazzs3quence 5 years ago.
Adds some more @since tags

Download all attachments as: .zip

Change History (20)

@ericlewis
5 years ago

#1 @ericlewis
5 years ago

  • Component changed from General to Widgets
  • Focuses docs added
  • Keywords has-patch commit added
  • Milestone changed from Awaiting Review to 4.1

#2 @DrewAPicture
5 years ago

  • Keywords needs-patch added; has-patch commit removed

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.

#3 @ericlewis
5 years ago

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
5 years ago

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

#4 @jazzs3quence
5 years ago

  • Keywords has-patch added; needs-patch removed

#5 @DrewAPicture
5 years ago

  • Milestone changed from 4.1 to Future Release

#6 @DrewAPicture
5 years ago

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

@blobaugh
5 years ago

Adding documentation to wp_list_widget_controls_dynamic_sidebar

@blobaugh
5 years ago

Added documentation to next_widget_id_number

@blobaugh
5 years ago

Added array parameter documentation to wp_widget_control

@jazzs3quence
5 years ago

Adds some more @since tags

#7 @DrewAPicture
5 years ago

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.

#8 @DrewAPicture
5 years ago

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.

#9 @DrewAPicture
5 years ago

In 30773:

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

See #30315.

#10 @DrewAPicture
5 years ago

In 30774:

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

See #30315.

#11 @DrewAPicture
5 years ago

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.

#12 @DrewAPicture
5 years ago

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.

#13 @DrewAPicture
5 years ago

In 30779:

Fix formatting in the DocBlock for wp_get_sidebars_widgets().

See #30315.

#14 @wonderboymusic
4 years ago

  • Milestone changed from Future Release to 4.1
  • Resolution set to fixed
  • Status changed from new to closed
  • Version set to 2.8
Note: See TracTickets for help on using tickets.