Introduce WP_Comment class to model/strongly-type rows from the comments database table. Inclusion of this class is a pre-req for some more general comment cleanup and sanity.

* Takes inspiration from `WP_Post` and adds sanity to comment caching. 
* Clarifies when the current global value for `$comment` is returned. The current implementation in `get_comment()` introduces side effects and an occasion stale global value for `$comment` when comment caches are cleaned.
* Strongly-types `@param` docs
* This class is marked `final` for now

Props wonderboymusic, nacin.

See #32619.

Built from https://develop.svn.wordpress.org/trunk@33891


git-svn-id: http://core.svn.wordpress.org/trunk@33860 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/includes/dashboard.php

@@ -548,10 +548,10 @@ function wp_dashboard_recent_drafts( $drafts = false ) {
 }
 
 /**
- * @global object $comment
+ * @global WP_Comment $comment
  *
- * @param object $comment
- * @param bool   $show_date
+ * @param WP_Comment $comment
+ * @param bool       $show_date
  */
 function _wp_dashboard_recent_comments_row( &$comment, $show_date = true ) {
 	$GLOBALS['comment'] =& $comment;
@@ -603,10 +603,10 @@ function _wp_dashboard_recent_comments_row( &$comment, $show_date = true ) {
 		 *
 		 * @since 2.6.0
 		 *
-		 * @param array  $actions An array of comment actions. Default actions include:
-		 *                        'Approve', 'Unapprove', 'Edit', 'Reply', 'Spam',
-		 *                        'Delete', and 'Trash'.
-		 * @param object $comment The comment object.
+		 * @param array      $actions An array of comment actions. Default actions include:
+		 *                            'Approve', 'Unapprove', 'Edit', 'Reply', 'Spam',
+		 *                            'Delete', and 'Trash'.
+		 * @param WP_Comment $comment The comment object.
 		 */
 		$actions = apply_filters( 'comment_row_actions', array_filter($actions), $comment );