Stop stripping new lines and instead make parsed post types post_content private

lib/class-file-reflector.php

@@ -4,6 +4,7 @@
 
 use phpDocumentor\Reflection;
 use phpDocumentor\Reflection\FileReflector;
+use PHPParser_Comment_Doc;
 
 /**
  * Reflection class for a full file.
@@ -44,6 +45,66 @@ class File_Reflector extends FileReflector {
 	 */
 	protected $last_doc = null;
 
+	/**
+	 * Grab and store the raw doc comment for the file if present.
+	 *
+	 * Note much of this logic mirrors what is in the parent class for storing
+	 * the file's doc_block key, but it doesn't provide any access to the raw
+	 * text of the comment. Since we are interested in having the raw text
+	 * available, we run the same logic here and store the text  instead of a
+	 * docblock reflection objet.
+	 *
+	 * @param  array  $nodes The nodes that will be traversed in this file.
+	 * @return array         The nodes to traverse for this file.
+	 */
+	public function beforeTraverse(array $nodes) {
+		$node = null;
+		$key = 0;
+		foreach ($nodes as $k => $n) {
+			if (!$n instanceof PHPParser_Node_Stmt_InlineHTML) {
+				$node = $n;
+				$key = $k;
+				break;
+			}
+		}
+
+		if ($node) {
+			$comments = (array) $node->getAttribute('comments');
+
+			// remove non-DocBlock comments
+			$comments = array_values(
+				array_filter(
+					$comments,
+					function ($comment) {
+						return $comment instanceof PHPParser_Comment_Doc;
+					}
+				)
+			);
+
+			if ( ! empty( $comments ) ) {
+				// the first DocBlock in a file documents the file if
+				// * it precedes another DocBlock or
+				// * it contains a @package tag and doesn't precede a class
+				//   declaration or
+				// * it precedes a non-documentable element (thus no include,
+				//   require, class, function, define, const)
+				if (
+					count( $comments ) > 1
+					|| ( ! $node instanceof PHPParser_Node_Stmt_Class
+					&& ! $node instanceof PHPParser_Node_Stmt_Interface
+					&& -1 !== strpos( $comments[0], '@package' ) )
+					|| ! $this->isNodeDocumentable( $node )
+				) {
+					$this->doc_comment = $comments[0];
+				}
+			}
+		}
+
+		$nodes = parent::beforeTraverse( $nodes );
+
+		return $nodes;
+	}
+
 	/**
 	 * Add hooks to the queue and update the node stack when we enter a node.
 	 *

lib/class-importer.php

@@ -379,15 +379,15 @@ public function import_hook( array $data, $parent_post_id = 0, $import_ignored =
 		$skip_duplicates = apply_filters( 'wp_parser_skip_duplicate_hooks', false );
 
 		if ( false !== $skip_duplicates ) {
-			if ( 0 === strpos( $data['doc']['description'], 'This action is documented in' ) ) {
+			if ( 0 === strpos( $data['doc']['summary'], 'This action is documented in' ) ) {
 				return false;
 			}
 
-			if ( 0 === strpos( $data['doc']['description'], 'This filter is documented in' ) ) {
+			if ( 0 === strpos( $data['doc']['summary'], 'This filter is documented in' ) ) {
 				return false;
 			}
 
-			if ( '' === $data['doc']['description'] && '' === $data['doc']['long_description'] ) {
+			if ( '' === $data['doc']['summary'] && '' === $data['doc']['description'] ) {
 				return false;
 			}
 		}
@@ -517,13 +517,14 @@ public function import_item( array $data, $parent_post_id = 0, $import_ignored =
 		$post_data   = wp_parse_args(
 			$arg_overrides,
 			array(
-				'post_content' => $data['doc']['long_description'],
-				'post_excerpt' => $data['doc']['description'],
-				'post_name'    => $slug,
-				'post_parent'  => (int) $parent_post_id,
-				'post_status'  => 'publish',
-				'post_title'   => $data['name'],
-				'post_type'    => $this->post_type_function,
+				'post_content'          => $data['doc']['description'],
+				'post_content_filtered' => $data['doc']['raw_description'],
+				'post_excerpt'          => $data['doc']['summary'],
+				'post_name'             => $slug,
+				'post_parent'           => (int) $parent_post_id,
+				'post_status'           => 'publish',
+				'post_title'            => $data['name'],
+				'post_type'             => $this->post_type_function,
 			)
 		);
 
@@ -732,6 +733,7 @@ public function import_item( array $data, $parent_post_id = 0, $import_ignored =
 			$anything_updated[] = update_post_meta( $post_id, '_wp_parser_namespace', (string) addslashes( $data['namespace'] ) );
 		}
 
+		$anything_updated[] = update_post_meta( $post_id, '_wp_parser_raw_docblock', (string) $data['doc']['raw'] );
 		$anything_updated[] = update_post_meta( $post_id, '_wp-parser_line_num', (string) $data['line'] );
 		$anything_updated[] = update_post_meta( $post_id, '_wp-parser_end_line_num', (string) $data['end_line'] );
 		$anything_updated[] = update_post_meta( $post_id, '_wp-parser_tags', $data['doc']['tags'] );

lib/class-plugin.php

@@ -21,6 +21,7 @@ public function on_load() {
 
 		add_action( 'init', array( $this, 'register_post_types' ), 11 );
 		add_action( 'init', array( $this, 'register_taxonomies' ), 11 );
+		add_action( 'wp', array( $this, 'replace_autop' ), 11 );
 		add_filter( 'wp_parser_get_arguments', array( $this, 'make_args_safe' ) );
 		add_filter( 'wp_parser_return_type', array( $this, 'humanize_separator' ) );
 
@@ -35,7 +36,6 @@ public function register_post_types() {
 		$supports = array(
 			'comments',
 			'custom-fields',
-			'editor',
 			'excerpt',
 			'revisions',
 			'title',
@@ -255,4 +255,43 @@ public function sanitize_argument( &$value ) {
 	public function humanize_separator( $type ) {
 		return str_replace( '|', '<span class="wp-parser-item-type-or">' . _x( ' or ', 'separator', 'wp-parser' ) . '</span>', $type );
 	}
+
+	/**
+	 * Replaces the normal content autop with a custom version to skip parser types.
+	 *
+	 * By running this filter replacement late on the wp hook, plugins are given ample
+	 * time to remove autop themselves. If they have removed autop, then the maybe_autop
+	 * filter is not added. There are potentially conflicting edge cases, but this
+	 * should catch at least some of them.
+	 *
+	 * Other plugins can also remove this functionality fairly easily by removing the wp
+	 * hook and stopping this process if needed.
+	 */
+	public function replace_autop() {
+		if ( has_filter( 'the_content', 'wpautop' ) ) {
+			remove_filter( 'the_content', 'wpautop' );
+			add_filter( 'the_content', array( $this, 'maybe_autop' ) );
+		}
+	}
+
+	/**
+	 * Autop's all post content except for wp-parser types.
+	 *
+	 * @param  string $content The content to filter.
+	 * @return string          The filtered content, conditionally with autop run.
+	 */
+	public function maybe_autop( $content ) {
+		// Get and cache the blacklist
+		static $blacklist;
+		if ( is_null( $blacklist ) ) {
+			$blacklist = apply_filters( 'wp_parser_autop_blacklist', array(
+				'wp-parser-function' => true,
+				'wp-parser-hook'     => true,
+				'wp-parser-class'    => true,
+				'wp-parser-method'   => true,
+			) );
+		}
+
+		return ( isset( $blacklist[ get_post_type() ] ) ) ? $content : wpautop( $content );
+	}
 }

lib/runner.php

@@ -140,24 +140,38 @@ function parse_files( $files, $root ) {
  */
 function export_docblock( $element ) {
 	$docblock = $element->getDocBlock();
+
 	if ( ! $docblock ) {
-		return array(
-			'description'      => '',
-			'long_description' => '',
-			'tags'             => array(),
+			return array(
+			'raw'             => '',
+			'summary'         => '',
+			'description'     => '',
+			'raw_description' => '',
+			'tags'            => array(),
 		);
 	}
 
+	// Extract the raw doc comment
+	if ( $element instanceof BaseReflector ) {
+		$raw_doc = (string) $element->getNode()->getDocComment();
+	} elseif ( $element instanceof File_Reflector && isset( $element->doc_comment ) ) {
+		$raw_doc = (string) $element->doc_comment->getText();
+	} else {
+		$raw_doc = '';
+	}
+
 	$output = array(
-		'description'      => preg_replace( '/[\n\r]+/', ' ', $docblock->getShortDescription() ),
-		'long_description' => preg_replace( '/[\n\r]+/', ' ', $docblock->getLongDescription()->getFormattedContents() ),
-		'tags'             => array(),
+		'raw'             => $raw_doc,
+		'summary'         => $docblock->getShortDescription(),
+		'description'     => $docblock->getLongDescription()->getFormattedContents(),
+		'raw_description' => $docblock->getLongDescription()->getContents(),
+		'tags'            => array(),
 	);
 
 	foreach ( $docblock->getTags() as $tag ) {
 		$tag_data = array(
 			'name'    => $tag->getName(),
-			'content' => preg_replace( '/[\n\r]+/', ' ', format_description( $tag->getDescription() ) ),
+			'content' => format_description( $tag->getDescription() ),
 		);
 		if ( method_exists( $tag, 'getTypes' ) ) {
 			$tag_data['types'] = $tag->getTypes();
@@ -176,7 +190,7 @@ function export_docblock( $element ) {
 			}
 			// Description string.
 			if ( method_exists( $tag, 'getDescription' ) ) {
-				$description = preg_replace( '/[\n\r]+/', ' ', format_description( $tag->getDescription() ) );
+				$description = format_description( $tag->getDescription() );
 				if ( ! empty( $description ) ) {
 					$tag_data['description'] = $description;
 				}

tests/phpunit/includes/export-testcase.php

@@ -457,6 +457,38 @@ protected function find_entity_data_in( $data, $type, $entity ) {
 		return false;
 	}
 
+	/**
+	 * Compact an array of strings to a multi-line string.
+	 *
+	 * @param  array  $lines The array of lines to turn into a multi-line string.
+	 * @return string        The processed multi-line string.
+	 */
+	protected function multiline_string( array $lines ) {
+		return implode( "\n", $lines );
+	}
+
+	/**
+	 * Compact an array of strings into a docblock string.
+	 *
+	 * Takes an array of string, and creates a multi-line string starting with the
+	 * classic docblock /** and ending with the *+/ to close out the docblock. Each
+	 * line will have the whitespace param plus ' * ' added to it.
+	 *
+	 * @param  array  $lines      The array of lines to create a docblock string from.
+	 * @param  string $whitespace Optional. The whitespace to use in the docblocks.
+	 * @return string             The docblock string created from the array of lines.
+	 */
+	protected function make_docblock( array $lines, $whitespace = '' ) {
+		array_walk( $lines, function( &$line ) use ( $whitespace ) {
+			$line = ( empty( $line ) ) ? '' : ' ' . $line;
+			$line = $whitespace . ' *' . $line;
+		});
+		array_unshift( $lines, '/**' );
+		$lines[] = $whitespace . ' */';
+
+		return $this->multiline_string( $lines );
+	}
+
 	/**
 	 * Check if one entity uses another entity.
 	 *