Changeset 27291

Timestamp:

02/26/2014 06:15:03 PM (11 years ago)

Author:

DrewAPicture

Message:

Add inline documentation for properties and other inline docs fixes for WP_Adjacent_Post.

See #26937.

File:

• trunk/src/wp-includes/link-template.php (modified) (6 diffs)

trunk/src/wp-includes/link-template.php

@@ -1149 +1149 @@
  *
  * Based on the current or specified post, determines either the previous or
- * next post based on the criteria specified. Supports retrieving posts with the
- * same taxonomy terms and posts that lack specific terms.
+ * next post based on the criteria specified. Supports retrieving posts with
+ * the same taxonomy terms and posts that lack specific terms.
+ *
+ * @since 3.9.0
+ *
+ * @package WordPress
+ * @subpackage Template
  */
 class WP_Adjacent_Post {
+
+    /**
+     * Adjacent post object.
+     *
+     * @since 3.9.0
+     * @access public
+     * @var null|WP_Adjacent_Post
+     */
     public $adjacent_post = null;
 
+    /**
+     * Current post object.
+     *
+     * @since 3.9.0
+     * @access protected
+     * @var bool|WP_Post
+     */
     protected $current_post   = false;
+
+    /**
+     * 'previous' or 'next' type of adjacent post.
+     *
+     * @since 3.9.0
+     * @access protected
+     * @var string
+     */
     protected $adjacent       = 'previous';
+
     protected $taxonomy       = 'category';
+
+    /**
+     * Whether the post should be in a same taxonomy term.
+     *
+     * @since 3.9.0
+     * @access protected
+     * @var string
+     */
     protected $in_same_term   = false;
+
+    /**
+     * Excluded term IDs.
+     *
+     * @since 3.9.0
+     * @access protected
+     * @var string|array
+     */
     protected $excluded_terms = '';
 
@@ -1180 +1225 @@
      * Allow direct access to adjacent post from the class instance itself
      *
-     * @param string $property
+     * @param string $property Property to get.
      * @return mixed String when adjacent post is found and post property exists. Null when no adjacent post is found.
      */
@@ -1313 +1358 @@
      *
      * @param array $clauses
-     * @uses $this->filter_join_and_where()
-     * @uses $this->filter_sort()
-     * @filter post_clauses
      * @return array
      */
     public function filter( $clauses ) {
-        // Immediately deregister these legacy filters to avoid modifying
-        // any calls to WP_Query from filter callbacks hooked to WP_Query filters.
+        /*
+         * Immediately deregister these legacy filters to avoid modifying
+         * any calls to WP_Query from filter callbacks hooked to WP_Query filters.
+         */
         remove_filter( 'posts_clauses', array( $this, 'filter' ) );
 
-        // The `join` and `where` filters are identical in their parameters,
-        // so we can use the same approach for both.
+        /*
+         * The `join` and `where` filters are identical in their parameters,
+         * so we can use the same approach for both.
+         */
         foreach ( array( 'join', 'where' ) as $clause ) {
             if ( has_filter( 'get_' . $this->adjacent . '_post_' . $clause ) ) {
@@ -1331 +1377 @@
         }
 
-        // The legacy `sort` filter combined the ORDER BY and LIMIT clauses,
-        // while `WP_Query` does not, which requires special handling.
+        /*
+         * The legacy `sort` filter combined the ORDER BY and LIMIT clauses,
+         * while `WP_Query` does not, which requires special handling.
+         */
         if ( has_filter( 'get_' . $this->adjacent . '_post_sort' ) ) {
             $sort_clauses = $this->filter_sort( $clauses['orderby'], $clauses['limits'] );
@@ -1350 +1398 @@
     protected function filter_join_and_where( $value, $clause ) {
         /**
+         * @todo Minimal hook docs
          * @deprecated 3.9.0
          */
@@ -1378 +1427 @@
         // Split the string of one or two clauses into their respective array keys
         if ( false !== $has_order_by && false !== $has_limit ) {
-            // The LIMIT clause cannot appear before the ORDER BY clause in a valid query
-            // However, since the legacy filter would allow a user to invert the order, we maintain that handling so the same errors are triggered.
+            /*
+             * The LIMIT clause cannot appear before the ORDER BY clause in a valid query
+             * However, since the legacy filter would allow a user to invert the order,
+             * we maintain that handling so the same errors are triggered.
+             */
             if ( $has_order_by < $has_limit ) {
                 $orderby = trim( str_ireplace( 'order by', '', substr( $sort, 0, $has_limit ) ) );