From 4a381ab393aa503b95aca434cc76f69fddb42b5e Mon Sep 17 00:00:00 2001
From: Drew Jaynes <drewapicture@git.wordpress.org>
Date: Wed, 26 Feb 2014 18:15:03 +0000
Subject: [PATCH] Add inline documentation for properties and other inline docs
 fixes for `WP_Adjacent_Post`.

See #26937.


git-svn-id: https://develop.svn.wordpress.org/trunk@27291 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/link-template.php | 80 +++++++++++++++++++++++++------
 1 file changed, 66 insertions(+), 14 deletions(-)

diff --git a/src/wp-includes/link-template.php b/src/wp-includes/link-template.php
index 24ae2de88c..3784f6420a 100644
--- a/src/wp-includes/link-template.php
+++ b/src/wp-includes/link-template.php
@@ -1148,16 +1148,61 @@ function get_adjacent_post( $in_same_term = false, $excluded_terms = '', $previo
  * WordPress Adjacent Post API
  *
  * 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 = '';
 
 	/**
@@ -1179,7 +1224,7 @@ class WP_Adjacent_Post {
 	/**
 	 * 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.
 	 */
 	public function __get( $property ) {
@@ -1312,26 +1357,29 @@ class WP_Adjacent_Post {
 	 * Apply the deprecated filters to WP_Query's clauses.
 	 *
 	 * @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 ) ) {
 				$clauses[ $clause ] = $this->filter_join_and_where( $clauses[ $clause ], $clause );
 			}
 		}
 
-		// 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'] );
 			$clauses      = array_merge( $clauses, $sort_clauses );
@@ -1349,6 +1397,7 @@ class WP_Adjacent_Post {
 	 */
 	protected function filter_join_and_where( $value, $clause ) {
 		/**
+		 * @todo Minimal hook docs
 		 * @deprecated 3.9.0
 		 */
 		return apply_filters( 'get_' . $this->adjacent . '_post_' . $clause, $value, $this->in_same_term, $this->excluded_terms );
@@ -1377,8 +1426,11 @@ class WP_Adjacent_Post {
 
 		// 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 ) ) );
 				$limits  = trim( substr( $sort, $has_limit ) );