Changeset 33893 for trunk/src/wp-includes/class-wp-comment.php

Timestamp:

09/03/2015 07:57:15 PM (11 years ago)

Author:

DrewAPicture

Message:

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.

File:

• trunk/src/wp-includes/class-wp-comment.php (modified) (4 diffs)

trunk/src/wp-includes/class-wp-comment.php

@@ -1 +1 @@
 <?php
-
- /**
- * WordPress Comment class
+/**
+ * Comments API: WP_Comment object class
+ *
+ * @package WordPress
+ * @subpackage Comments
+ * @since 4.4.0
+ */
+
+/**
+ * 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
-         */
-        public $comment_author;
-        /**
+
+        /**
+         * Comment author ID.
+         *
+         * @since 4.4.0
+         * @access public
+         * @var string
+         */
+        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
          */
@@ -69 +151 @@
 
         /**
-         * Retrieve WP_Comment instance.
-         *
+         * Retrieves a WP_Comment instance.
+         *
+         * @since 4.4.0
+         * @access public
          * @static
-         * @access public
-         *
-         * @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 ) {
@@ -104 +187 @@
         /**
          * Constructor.
+         *
+         * Populates properties with object vars.
+         *
+         * @since 4.4.0
+         * @access public
          *
          * @param WP_Comment $comment Comment object.
@@ -113 +201 @@
         }
 
+        /**
+         * Convert object to array.
+         *
+         * @since 4.4.0
+         * @access public
+         *
+         * @return array Object as array.
+         */
         public function to_array() {
                 return get_object_vars( $this );