WordPress.org

Make WordPress Core

Opened 5 years ago

Closed 5 years ago

#34027 closed defect (bug) (fixed)

Improve method documentation for WP_Widget_Text

Reported by: DrewAPicture Owned by: DrewAPicture
Milestone: 4.4 Priority: normal
Severity: normal Version:
Component: Widgets Keywords: good-first-bug has-patch
Focuses: docs Cc:

Description

Note: This is part of the effort in #34013 to improve method documentation to all core widget classes

Class: WP_Widget_Text
File: wp-includes/widgets/class-wp-widget-text.php

Attachments (2)

34027.patch (1.7 KB) - added by leemon 5 years ago.
Improve method documentation
34027.2.patch (1.9 KB) - added by leemon 5 years ago.
Updated method descriptions

Download all attachments as: .zip

Change History (10)

@leemon
5 years ago

Improve method documentation

#1 @SergeyBiryukov
5 years ago

  • Keywords has-patch added; needs-patch removed
  • Milestone changed from Awaiting Review to 4.4

#2 @leemon
5 years ago

Added patch to improve the method docs for the widget(), update(), form(), and __construct() methods in the WP_Widget_Text class.

34027.patch

#3 @DrewAPicture
5 years ago

  • Keywords needs-patch added; has-patch removed

Hi @leemon,

Thanks for the patch!

Just a couple of notes:

  • Let's go with the vernacular of something like "the current {type} widget instance" instead of "a particular instance of a widget". Being general in the WP_Widget base class is fine, but in this context, we can be more specific. For example:
 * Handles updating settings for the current Text widget instance.
  • Notice I inserted the type of widget, in this case "Text", and more specifically mentioned updating the settings which is what the update() method does.
  • The same sort of advice goes along with any other method in the class

#4 follow-up: @leemon
5 years ago

Thanks for the clarification, Drew! You may have guessed that I'm a newbie.

Before creating the new patches, I'd like to be sure about the strings to use:

__construct(): Creates a new {type} widget instance.
widget(): Echoes the current {type} widget instance content.
update(): Handles updating settings for the current {type} widget instance.
form(): Outputs the current {type} widget instance settings update form.

What do you think?

Last edited 5 years ago by leemon (previous) (diff)

#5 in reply to: ↑ 4 @DrewAPicture
5 years ago

Replying to leemon:

Thanks for the clarification, Drew! You may have guessed that I'm a newbie.

Before creating the new patches, I'd like to be sure about the strings to use:

__construct(): Creates a new {type} widget instance.
widget(): Echoes the current {type} widget instance content.
update(): Handles updating settings for the current {type} widget instance.
form(): Outputs the current {type} widget instance settings update form.

What do you think?

Works for me :-)

@leemon
5 years ago

Updated method descriptions

#6 @leemon
5 years ago

  • Keywords has-patch added; needs-patch removed

#7 @DrewAPicture
5 years ago

Thanks @leemon, this looks great!

#8 @DrewAPicture
5 years ago

  • Owner set to DrewAPicture
  • Resolution set to fixed
  • Status changed from new to closed

In 34609:

Docs: Improve documentation for the __construct(), widget(), update(), and form() methods in WP_Widget_Text.

(first!) Props leemon.
Fixes #34027.

Note: See TracTickets for help on using tickets.