Docs: Add complete file, class, property, and method documentation for the new `WP_Comment` class, introduced in [33891].

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.

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


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

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 );
 	}

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.4-alpha-33892';
+$wp_version = '4.4-alpha-33893';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.