From f2af1a6a1ff8fd8889c8b96f1a4a4794c9e359e0 Mon Sep 17 00:00:00 2001
From: Drew Jaynes <drewapicture@git.wordpress.org>
Date: Sun, 27 Sep 2015 00:50:04 +0000
Subject: [PATCH] Docs: Improve documentation for the `__construct()`,
 `recent_comments_style()`, `widget()`, `update()`, and `form()` methods in
 `WP_Widget_Recent_Comments`.

Also fixes a typo in the class DocBlock.

Props leemon.
Fixes #34022. See #34013.


git-svn-id: https://develop.svn.wordpress.org/trunk@34614 602fd350-edb4-49c9-b593-d223f7449a82
---
 .../class-wp-widget-recent-comments.php       | 50 ++++++++++++++-----
 1 file changed, 38 insertions(+), 12 deletions(-)

diff --git a/src/wp-includes/widgets/class-wp-widget-recent-comments.php b/src/wp-includes/widgets/class-wp-widget-recent-comments.php
index 7bf5c6fb96..157205cdc9 100644
--- a/src/wp-includes/widgets/class-wp-widget-recent-comments.php
+++ b/src/wp-includes/widgets/class-wp-widget-recent-comments.php
@@ -8,7 +8,7 @@
  */
 
 /**
- * Core class used to implement a Recent_Comments widget.
+ * Core class used to implement a Recent Comments widget.
  *
  * @since 2.8.0
  *
@@ -16,6 +16,12 @@
  */
 class WP_Widget_Recent_Comments extends WP_Widget {
 
+	/**
+	 * Sets up a new Recent Comments widget instance.
+	 *
+	 * @since 2.8.0
+	 * @access public
+	 */
 	public function __construct() {
 		$widget_ops = array('classname' => 'widget_recent_comments', 'description' => __( 'Your site&#8217;s most recent comments.' ) );
 		parent::__construct('recent-comments', __('Recent Comments'), $widget_ops);
@@ -25,7 +31,10 @@ class WP_Widget_Recent_Comments extends WP_Widget {
 			add_action( 'wp_head', array($this, 'recent_comments_style') );
 	}
 
-	/**
+ 	/**
+	 * Outputs the default styles for the Recent Comments widget.
+	 *
+	 * @since 2.8.0
 	 * @access public
 	 */
 	public function recent_comments_style() {
@@ -41,13 +50,19 @@ class WP_Widget_Recent_Comments extends WP_Widget {
 			|| ! apply_filters( 'show_recent_comments_widget_style', true, $this->id_base ) )
 			return;
 		?>
-	<style type="text/css">.recentcomments a{display:inline !important;padding:0 !important;margin:0 !important;}</style>
-<?php
+		<style type="text/css">.recentcomments a{display:inline !important;padding:0 !important;margin:0 !important;}</style>
+		<?php
 	}
 
 	/**
-	 * @param array $args
-	 * @param array $instance
+	 * Outputs the content for the current Recent Comments widget instance.
+	 *
+	 * @since 2.8.0
+	 * @access public
+	 *
+	 * @param array $args     Display arguments including 'before_title', 'after_title',
+	 *                        'before_widget', and 'after_widget'.
+	 * @param array $instance Settings for the current Recent Comments widget instance.
 	 */
 	public function widget( $args, $instance ) {
 		if ( ! isset( $args['widget_id'] ) )
@@ -107,9 +122,15 @@ class WP_Widget_Recent_Comments extends WP_Widget {
 	}
 
 	/**
-	 * @param array $new_instance
-	 * @param array $old_instance
-	 * @return array
+	 * Handles updating settings for the current Recent Comments widget instance.
+	 *
+	 * @since 2.8.0
+	 * @access public
+	 *
+	 * @param array $new_instance New settings for this instance as input by the user via
+	 *                            WP_Widget::form().
+	 * @param array $old_instance Old settings for this instance.
+	 * @return array Updated settings to save.
 	 */
 	public function update( $new_instance, $old_instance ) {
 		$instance = $old_instance;
@@ -119,17 +140,22 @@ class WP_Widget_Recent_Comments extends WP_Widget {
 	}
 
 	/**
-	 * @param array $instance
+	 * Outputs the settings form for the Recent Comments widget.
+	 *
+	 * @since 2.8.0
+	 * @access public
+	 *
+	 * @param array $instance Current settings.
 	 */
 	public function form( $instance ) {
 		$title = isset( $instance['title'] ) ? $instance['title'] : '';
 		$number = isset( $instance['number'] ) ? absint( $instance['number'] ) : 5;
-?>
+		?>
 		<p><label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( 'Title:' ); ?></label>
 		<input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>" /></p>
 
 		<p><label for="<?php echo $this->get_field_id( 'number' ); ?>"><?php _e( 'Number of comments to show:' ); ?></label>
 		<input class="tiny-text" id="<?php echo $this->get_field_id( 'number' ); ?>" name="<?php echo $this->get_field_name( 'number' ); ?>" type="number" step="1" min="1" value="<?php echo $number; ?>" size="3" /></p>
-<?php
+		<?php
 	}
 }