WordPress 4.5
[autoinstalls/wordpress.git] / wp-includes / class-walker-comment.php
index e82ec669e42a672b45b1139633bb16bb61ae1f2c..3065744e50727a03dbf6e3cb6a1a4f1727b858eb 100644 (file)
@@ -8,44 +8,49 @@
  */
 
 /**
- * HTML comment list class.
+ * Core walker class used to create an HTML list of comments.
  *
- * @uses Walker
  * @since 2.7.0
+ *
+ * @see Walker
  */
 class Walker_Comment extends Walker {
+
        /**
         * What the class handles.
         *
-        * @see Walker::$tree_type
-        *
         * @since 2.7.0
+        * @access public
         * @var string
+        *
+        * @see Walker::$tree_type
         */
        public $tree_type = 'comment';
 
        /**
-        * DB fields to use.
-        *
-        * @see Walker::$db_fields
+        * Database fields to use.
         *
         * @since 2.7.0
+        * @access public
         * @var array
+        *
+        * @see Walker::$db_fields
+        * @todo Decouple this
         */
        public $db_fields = array ('parent' => 'comment_parent', 'id' => 'comment_ID');
 
        /**
-        * Start the list before the elements are added.
-        *
-        * @see Walker::start_lvl()
+        * Starts the list before the elements are added.
         *
         * @since 2.7.0
+        * @access public
         *
+        * @see Walker::start_lvl()
         * @global int $comment_depth
         *
         * @param string $output Passed by reference. Used to append additional content.
-        * @param int $depth Depth of comment.
-        * @param array $args Uses 'style' argument for type of HTML list.
+        * @param int    $depth  Optional. Depth of the current comment. Default 0.
+        * @param array  $args   Optional. Uses 'style' argument for type of HTML list. Default empty array.
         */
        public function start_lvl( &$output, $depth = 0, $args = array() ) {
                $GLOBALS['comment_depth'] = $depth + 1;
@@ -64,17 +69,18 @@ class Walker_Comment extends Walker {
        }
 
        /**
-        * End the list of items after the elements are added.
-        *
-        * @see Walker::end_lvl()
+        * Ends the list of items after the elements are added.
         *
         * @since 2.7.0
+        * @access public
         *
+        * @see Walker::end_lvl()
         * @global int $comment_depth
         *
         * @param string $output Passed by reference. Used to append additional content.
-        * @param int    $depth  Depth of comment.
-        * @param array  $args   Will only append content if style argument value is 'ol' or 'ul'.
+        * @param int    $depth  Optional. Depth of the current comment. Default 0.
+        * @param array  $args   Optional. Will only append content if style argument value is 'ol' or 'ul'.
+        *                       Default empty array.
         */
        public function end_lvl( &$output, $depth = 0, $args = array() ) {
                $GLOBALS['comment_depth'] = $depth + 1;
@@ -93,7 +99,7 @@ class Walker_Comment extends Walker {
        }
 
        /**
-        * Traverse elements to create list from elements.
+        * Traverses elements to create list from elements.
         *
         * This function is designed to enhance Walker::display_element() to
         * display children of higher nesting levels than selected inline on
@@ -111,17 +117,18 @@ class Walker_Comment extends Walker {
         *     2
         *      2.2
         *
+        * @since 2.7.0
+        * @access public
+        *
         * @see Walker::display_element()
         * @see wp_list_comments()
         *
-        * @since 2.7.0
-        *
-        * @param object $element           Data object.
-        * @param array  $children_elements List of elements to continue traversing.
-        * @param int    $max_depth         Max depth to traverse.
-        * @param int    $depth             Depth of current element.
-        * @param array  $args              An array of arguments.
-        * @param string $output            Passed by reference. Used to append additional content.
+        * @param WP_Comment $element           Comment data object.
+        * @param array      $children_elements List of elements to continue traversing. Passed by reference.
+        * @param int        $max_depth         Max depth to traverse.
+        * @param int        $depth             Depth of the current element.
+        * @param array      $args              An array of arguments.
+        * @param string     $output            Used to append additional content. Passed by reference.
         */
        public function display_element( $element, &$children_elements, $max_depth, $depth, $args, &$output ) {
                if ( !$element )
@@ -133,9 +140,9 @@ class Walker_Comment extends Walker {
                parent::display_element( $element, $children_elements, $max_depth, $depth, $args, $output );
 
                /*
-                * If we're at the max depth, and the current element still has children,
-                * loop over those and display them at this level. This is to prevent them
-                * being orphaned to the end of the list.
+                * If at the max depth, and the current element still has children, loop over those
+                * and display them at this level. This is to prevent them being orphaned to the end
+                * of the list.
                 */
                if ( $max_depth <= $depth + 1 && isset( $children_elements[$id]) ) {
                        foreach ( $children_elements[ $id ] as $child )
@@ -147,20 +154,21 @@ class Walker_Comment extends Walker {
        }
 
        /**
-        * Start the element output.
+        * Starts the element output.
         *
         * @since 2.7.0
+        * @access public
         *
         * @see Walker::start_el()
         * @see wp_list_comments()
-        *
         * @global int        $comment_depth
         * @global WP_Comment $comment
         *
-        * @param string $output  Passed by reference. Used to append additional content.
-        * @param object $comment Comment data object.
-        * @param int    $depth   Depth of comment in reference to parents.
-        * @param array  $args    An array of arguments.
+        * @param string     $output  Used to append additional content. Passed by reference.
+        * @param WP_Comment $comment Comment data object.
+        * @param int        $depth   Optional. Depth of the current comment in reference to parents. Default 0.
+        * @param array      $args    Optional. An array of arguments. Default empty array.
+        * @param int        $id      Optional. ID of the current comment. Default 0 (unused).
         */
        public function start_el( &$output, $comment, $depth = 0, $args = array(), $id = 0 ) {
                $depth++;
@@ -193,14 +201,15 @@ class Walker_Comment extends Walker {
         * Ends the element output, if needed.
         *
         * @since 2.7.0
+        * @access public
         *
         * @see Walker::end_el()
         * @see wp_list_comments()
         *
-        * @param string     $output  Passed by reference. Used to append additional content.
-        * @param WP_Comment $comment The comment object. Default current comment.
-        * @param int        $depth   Depth of comment.
-        * @param array      $args    An array of arguments.
+        * @param string     $output  Used to append additional content. Passed by reference.
+        * @param WP_Comment $comment The current comment object. Default current comment.
+        * @param int        $depth   Optional. Depth of the current comment. Default 0.
+        * @param array      $args    Optional. An array of arguments. Default empty array.
         */
        public function end_el( &$output, $comment, $depth = 0, $args = array() ) {
                if ( !empty( $args['end-callback'] ) ) {
@@ -216,15 +225,15 @@ class Walker_Comment extends Walker {
        }
 
        /**
-        * Output a pingback comment.
+        * Outputs a pingback comment.
         *
-        * @access protected
         * @since 3.6.0
+        * @access protected
         *
         * @see wp_list_comments()
         *
         * @param WP_Comment $comment The comment object.
-        * @param int        $depth   Depth of comment.
+        * @param int        $depth   Depth of the current comment.
         * @param array      $args    An array of arguments.
         */
        protected function ping( $comment, $depth, $args ) {
@@ -238,16 +247,16 @@ class Walker_Comment extends Walker {
        }
 
        /**
-        * Output a single comment.
+        * Outputs a single comment.
         *
-        * @access protected
         * @since 3.6.0
+        * @access protected
         *
         * @see wp_list_comments()
         *
-        * @param object $comment Comment to display.
-        * @param int    $depth   Depth of comment.
-        * @param array  $args    An array of arguments.
+        * @param WP_Comment $comment Comment to display.
+        * @param int        $depth   Depth of the current comment.
+        * @param array      $args    An array of arguments.
         */
        protected function comment( $comment, $depth, $args ) {
                if ( 'div' == $args['style'] ) {
@@ -297,16 +306,16 @@ class Walker_Comment extends Walker {
        }
 
        /**
-        * Output a comment in the HTML5 format.
+        * Outputs a comment in the HTML5 format.
         *
-        * @access protected
         * @since 3.6.0
+        * @access protected
         *
         * @see wp_list_comments()
         *
-        * @param object $comment Comment to display.
-        * @param int    $depth   Depth of comment.
-        * @param array  $args    An array of arguments.
+        * @param WP_Comment $comment Comment to display.
+        * @param int        $depth   Depth of the current comment.
+        * @param array      $args    An array of arguments.
         */
        protected function html5_comment( $comment, $depth, $args ) {
                $tag = ( 'div' === $args['style'] ) ? 'div' : 'li';