Pick up docs for filters in condition expressions

lib/class-file-reflector.php

@@ -38,11 +38,11 @@ class File_Reflector extends FileReflector {
 	protected $location = array();
 
 	/**
-	 * Last DocBlock associated with a non-documentable element.
+	 * Last DocBlock(s) associated with a non-documentable element(s).
 	 *
-	 * @var \PHPParser_Comment_Doc
+	 * @var \PHPParser_Comment_Doc[]
 	 */
-	protected $last_doc = null;
+	protected $last_doc = array();
 
 	/**
 	 * Add hooks to the queue and update the node stack when we enter a node.
@@ -83,8 +83,8 @@ public function enterNode( \PHPParser_Node $node ) {
 
 				if ( $this->isFilter( $node ) ) {
 					if ( $this->last_doc && ! $node->getDocComment() ) {
-						$node->setAttribute( 'comments', array( $this->last_doc ) );
-						$this->last_doc = null;
+						$last_doc = array_pop( $this->last_doc );
+						$node->setAttribute( 'comments', array( $last_doc ) );
 					}
 
 					$hook = new Hook_Reflector( $node, $this->context );
@@ -127,7 +127,11 @@ public function enterNode( \PHPParser_Node $node ) {
 		// associated with a named element, and so aren't really from a non-
 		// documentable element after all.
 		if ( ! $this->isNodeDocumentable( $node ) && 'Name' !== $node->getType() && ( $docblock = $node->getDocComment() ) ) {
-			$this->last_doc = $docblock;
+			// The same docblock can be associated with multiple non-documentable
+			// elements, so we have to take care not to save the same docblock twice.
+			if ( ! $this->last_doc || $docblock->getText() !== end( $this->last_doc )->getText() ) {
+				$this->last_doc[] = $docblock;
+			}
 		}
 	}
 

tests/phpunit/includes/export-testcase.php

@@ -14,7 +14,7 @@ class Export_UnitTestCase extends \WP_UnitTestCase {
 	/**
 	 * The exported data.
 	 *
-	 * @var string
+	 * @var array
 	 */
 	protected $export_data;
 
@@ -424,8 +424,8 @@ protected function assertPropertyHasDocs( $class, $property, $docs ) {
 	/**
 	 * Assert that a hook has a docblock.
 	 *
-	 * @param array $hook The hook name.
-	 * @param array $docs The expected data for the hook's docblock.
+	 * @param string $hook The hook name.
+	 * @param array  $docs The expected data for the hook's docblock.
 	 */
 	protected function assertHookHasDocs( $hook, $docs ) {
 
@@ -436,9 +436,9 @@ protected function assertHookHasDocs( $hook, $docs ) {
 	/**
 	 * Find the exported data for an entity.
 	 *
-	 * @param array  $data        The data to search in.
-	 * @param string $type        The type of entity.
-	 * @param string $entity_name The name of the function.
+	 * @param array  $data   The data to search in.
+	 * @param string $type   The type of entity.
+	 * @param string $entity The name of the entity.
 	 *
 	 * @return array|false The data for the entity, or false if it couldn't be found.
 	 */

tests/phpunit/tests/export/docblocks.inc

@@ -88,3 +88,13 @@ do_action( 'undocumented_hook' );
  * A reference array action.
  */
 do_action_ref_array( 'test_ref_array_action', array( &$var ) );
+
+/**
+ * A filter in a conditional expression.
+ */
+if ( apply_filters( 'in_conditional_expression', true ) ) {
+	/**
+	 * A filter in a conditional.
+	 */
+	$value = apply_filters( 'in_conditional', true );
+}

tests/phpunit/tests/export/docblocks.php

@@ -59,6 +59,16 @@ public function test_hook_docblocks() {
 			'test_ref_array_filter'
 			, array( 'description' => 'A reference array filter.' )
 		);
+
+		$this->assertHookHasDocs(
+			'in_conditional_expression'
+			, array( 'description' => 'A filter in a conditional expression.' )
+		);
+
+		$this->assertHookHasDocs(
+			'in_conditional'
+			, array( 'description' => 'A filter in a conditional.' )
+		);
 	}
 
 	/**