From 46af2b9cd900d5f6f65801732646f5b30d8251d3 Mon Sep 17 00:00:00 2001
From: Drew Jaynes <drewapicture@git.wordpress.org>
Date: Thu, 3 Sep 2015 19:57:15 +0000
Subject: [PATCH] Docs: Add complete file, class, property, and method
 documentation for the new `WP_Comment` class, introduced in [33891].
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

It's important for new functionality, especially something as significant as a new class to have complete documentation upon initial commit – not after the fact.

See #32619.


git-svn-id: https://develop.svn.wordpress.org/trunk@33893 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/class-wp-comment.php | 112 +++++++++++++++++++++++++--
 1 file changed, 104 insertions(+), 8 deletions(-)

diff --git a/src/wp-includes/class-wp-comment.php b/src/wp-includes/class-wp-comment.php
index b1898995bb..753ab39dbd 100644
--- a/src/wp-includes/class-wp-comment.php
+++ b/src/wp-includes/class-wp-comment.php
@@ -1,82 +1,165 @@
 <?php
+/**
+ * Comments API: WP_Comment object class
+ *
+ * @package WordPress
+ * @subpackage Comments
+ * @since 4.4.0
+ */
 
- /**
- * WordPress Comment class
+/**
+ * Core class used to organize comments as instantiated objects with defined members.
  *
  * @since 4.4.0
  */
 final class WP_Comment {
+
 	/**
+	 * Comment ID.
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var int
 	 */
 	public $comment_ID;
+
 	/**
+	 * ID of the post the comment is associated with.
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var int
 	 */
 	public $comment_post_ID = 0;
+
 	/**
-	 * @var int
+	 * Comment author ID.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 * @var string
 	 */
-	public $comment_author;
+	public $comment_author = '';
+
 	/**
+	 * Comment author email address.
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var string
 	 */
 	public $comment_author_email = '';
+
 	/**
+	 * Comment author URL.
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var string
 	 */
 	public $comment_author_url = '';
+
 	/**
+	 * Comment author IP address (IPv4 format).
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var string
 	 */
 	public $comment_author_IP = '';
+
 	/**
+	 * Comment date in YYYY-MM-DD HH:MM:SS format.
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var string
 	 */
 	public $comment_date = '0000-00-00 00:00:00';
+
 	/**
+	 * Comment GMT date in YYYY-MM-DD HH::MM:SS format.
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var string
 	 */
 	public $comment_date_gmt = '0000-00-00 00:00:00';
+
 	/**
+	 * Comment content.
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var string
 	 */
 	public $comment_content;
+
 	/**
+	 * Comment karma count.
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var int
 	 */
 	public $comment_karma = 0;
+
 	/**
+	 * Comment approval status.
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var string
 	 */
 	public $comment_approved = '1';
+
 	/**
+	 * Comment author HTTP user agent.
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var string
 	 */
 	public $comment_agent = '';
+
 	/**
+	 * Comment type.
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var string
 	 */
 	public $comment_type = '';
+
 	/**
+	 * Parent comment ID.
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var int
 	 */
 	public $comment_parent = 0;
+
 	/**
+	 * Comment author ID.
+	 *
+	 * @since 4.4.0
+	 * @access public
 	 * @var int
 	 */
 	public $user_id = 0;
 
 	/**
-	 * Retrieve WP_Comment instance.
+	 * Retrieves a WP_Comment instance.
 	 *
-	 * @static
+	 * @since 4.4.0
 	 * @access public
+	 * @static
 	 *
-	 * @global wpdb $wpdb
+	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
 	 * @param int $id Comment ID.
-	 * @return WP_Comment|false Comment object, false otherwise.
+	 * @return WP_Comment|false Comment object, otherwise false.
 	 */
 	public static function get_instance( $id ) {
 		global $wpdb;
@@ -104,6 +187,11 @@ final class WP_Comment {
 	/**
 	 * Constructor.
 	 *
+	 * Populates properties with object vars.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 *
 	 * @param WP_Comment $comment Comment object.
 	 */
 	public function __construct( $comment ) {
@@ -112,6 +200,14 @@ final class WP_Comment {
 		}
 	}
 
+	/**
+	 * Convert object to array.
+	 *
+	 * @since 4.4.0
+	 * @access public
+	 *
+	 * @return array Object as array.
+	 */
 	public function to_array() {
 		return get_object_vars( $this );
 	}