From 2f64100369178ed934020027ff428c41f268d957 Mon Sep 17 00:00:00 2001
From: "Drew Jaynes (DrewAPicture)" <drewapicture@git.wordpress.org>
Date: Mon, 1 Dec 2014 19:34:25 +0000
Subject: [PATCH] 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.


git-svn-id: https://develop.svn.wordpress.org/trunk@30691 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/widgets.php | 27 ++++++++++++++++++---------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/src/wp-includes/widgets.php b/src/wp-includes/widgets.php
index f6137003fb..0a8f03643f 100644
--- a/src/wp-includes/widgets.php
+++ b/src/wp-includes/widgets.php
@@ -132,14 +132,18 @@ class WP_Widget {
 	}
 
 	/**
-	 * Constructs id attributes for use in form() fields
+	 * Constructs id attributes for use in {@see WP_Widget::form()} fields.
 	 *
-	 * This function should be used in form() methods to create id attributes for fields to be saved by update()
+	 * This function should be used in form() methods to create id attributes
+	 * for fields to be saved by {@see WP_Widget::update()}.
 	 *
-	 * @param string $field_name Field name
-	 * @return string ID attribute for $field_name
+	 * @since 2.8.0
+	 * @access public
+	 *
+	 * @param string $field_name Field name.
+	 * @return string ID attribute for `$field_name`.
 	 */
-	public function get_field_id($field_name) {
+	public function get_field_id( $field_name ) {
 		return 'widget-' . $this->id_base . '-' . $this->number . '-' . $field_name;
 	}
 
@@ -220,6 +224,7 @@ class WP_Widget {
 	 *
 	 * Finds the instance and calls {@see WP_Widget::widget()}.
 	 *
+	 * @since 2.8.0
 	 * @access public
 	 *
 	 * @param array     $args        Display arguments. See {@see WP_Widget::widget()} for information
@@ -273,9 +278,10 @@ class WP_Widget {
 	}
 
 	/**
-	 * Deal with changed settings.
+	 * Deal with changed settings (Do NOT override).
 	 *
-	 * Do NOT over-ride this function.
+	 * @since 2.8.0
+	 * @access public
 	 *
 	 * @param int $deprecated Not used.
 	 */
@@ -355,9 +361,12 @@ class WP_Widget {
 	}
 
 	/**
-	 * Generate the control form.
+	 * Generate the widget control form (Do NOT override).
 	 *
-	 * Do NOT over-ride this function.
+	 * @since 2.8.0
+	 * @access public
+	 *
+	 * @param int|array $widget_args Widget instance number or array of widget arguments.
 	 */
 	public function form_callback( $widget_args = 1 ) {
 		if ( is_numeric($widget_args) )