diff --git a/composer.lock b/composer.lock
index 87d3494..025adcd 100644
--- a/composer.lock
+++ b/composer.lock
@@ -1,11 +1,10 @@
{
"_readme": [
"This file locks the dependencies of your project to a known state",
- "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file",
+ "Read more about it at http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file",
"This file is @generated automatically"
],
- "hash": "a6b6b77caa783549c8eda9ef2cc489fb",
- "content-hash": "81428b7705fd3ea26dd058625d6527c9",
+ "hash": "7f8182189ed845514079dae0bb6fbc34",
"packages": [
{
"name": "composer/installers",
diff --git a/lib/class-file-reflector.php b/lib/class-file-reflector.php
index 5e1b59f..8233688 100644
--- a/lib/class-file-reflector.php
+++ b/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.
*
diff --git a/lib/class-importer.php b/lib/class-importer.php
index b37f8cd..e1719f9 100644
--- a/lib/class-importer.php
+++ b/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'] );
diff --git a/lib/class-plugin.php b/lib/class-plugin.php
index 5fe7f95..cd47b72 100644
--- a/lib/class-plugin.php
+++ b/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( '|', '' . _x( ' or ', 'separator', 'wp-parser' ) . '', $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 );
+ }
}
diff --git a/lib/runner.php b/lib/runner.php
index 9022e04..3d4a7df 100644
--- a/lib/runner.php
+++ b/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;
}
diff --git a/tests/phpunit/includes/export-testcase.php b/tests/phpunit/includes/export-testcase.php
index b3fe845..f4607e9 100644
--- a/tests/phpunit/includes/export-testcase.php
+++ b/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.
*
diff --git a/tests/phpunit/tests/export/docblocks.php b/tests/phpunit/tests/export/docblocks.php
index 0d49b15..4b8afeb 100644
--- a/tests/phpunit/tests/export/docblocks.php
+++ b/tests/phpunit/tests/export/docblocks.php
@@ -11,26 +11,16 @@
*/
class Export_Docblocks extends Export_UnitTestCase {
- /**
- * Test that line breaks are removed when the description is exported.
- */
- public function test_linebreaks_removed() {
-
- $this->assertStringMatchesFormat(
- '%s'
- , $this->export_data['classes'][0]['doc']['long_description']
- );
- }
-
/**
* Test that hooks which aren't documented don't receive docs from another node.
*/
public function test_undocumented_hook() {
$this->assertHookHasDocs(
- 'undocumented_hook'
- , array(
- 'description' => '',
+ 'undocumented_hook',
+ array(
+ 'raw' => '',
+ 'summary' => '',
)
);
}
@@ -41,23 +31,53 @@ public function test_undocumented_hook() {
public function test_hook_docblocks() {
$this->assertHookHasDocs(
- 'test_action'
- , array( 'description' => 'A test action.' )
+ 'test_action',
+ array(
+ 'raw' => $this->make_docblock( array(
+ 'A test action.',
+ '',
+ '@since 3.7.0',
+ '',
+ '@param WP_Post $post Post object.',
+ ) ),
+ 'summary' => 'A test action.',
+ 'tags' => array(
+ array(
+ 'name' => 'since',
+ 'content' => '3.7.0',
+ ),
+ array(
+ 'name' => 'param',
+ 'types' => array( '\WP_Post' ),
+ 'variable' => '$post',
+ 'content' => 'Post object.'
+ )
+ )
+ )
);
$this->assertHookHasDocs(
- 'test_filter'
- , array( 'description' => 'A filter.' )
+ 'test_filter',
+ array(
+ 'raw' => $this->make_docblock( array( 'A filter.' ) ),
+ 'summary' => 'A filter.',
+ )
);
$this->assertHookHasDocs(
- 'test_ref_array_action'
- , array( 'description' => 'A reference array action.' )
+ 'test_ref_array_action',
+ array(
+ 'raw' => $this->make_docblock( array( 'A reference array action.' ) ),
+ 'summary' => 'A reference array action.',
+ )
);
$this->assertHookHasDocs(
- 'test_ref_array_filter'
- , array( 'description' => 'A reference array filter.' )
+ 'test_ref_array_filter',
+ array(
+ 'raw' => $this->make_docblock( array( 'A reference array filter.' ) ),
+ 'summary' => 'A reference array filter.'
+ )
);
}
@@ -65,9 +85,35 @@ public function test_hook_docblocks() {
* Test that file-level docs are exported.
*/
public function test_file_docblocks() {
-
$this->assertFileHasDocs(
- array( 'description' => 'This is the file-level docblock summary.' )
+ array(
+ 'raw' => $this->make_docblock( array(
+ 'This is the file-level docblock summary.',
+ '',
+ 'This is the file-level docblock description, which may span multiple lines. In',
+ 'fact, this one does. It spans more than two full lines, continuing on to the',
+ 'third line.',
+ '',
+ '@since 1.5.0',
+ ) ),
+ 'summary' => 'This is the file-level docblock summary.',
+ 'description' => $this->multiline_string( array(
+ 'This is the file-level docblock description, which may span multiple lines. In',
+ 'fact, this one does. It spans more than two full lines, continuing on to the',
+ 'third line.
',
+ ) ),
+ 'raw_description' => $this->multiline_string( array(
+ 'This is the file-level docblock description, which may span multiple lines. In',
+ 'fact, this one does. It spans more than two full lines, continuing on to the',
+ 'third line.',
+ ) ),
+ 'tags' => array(
+ array(
+ 'name' => 'since',
+ 'content' => '1.5.0',
+ )
+ )
+ )
);
}
@@ -77,10 +123,23 @@ public function test_file_docblocks() {
public function test_function_docblocks() {
$this->assertFunctionHasDocs(
- 'test_func'
- , array(
- 'description' => 'This is a function docblock.',
- 'long_description' => 'This function is just a test, but we\'ve added this description anyway.
',
+ 'test_func',
+ array(
+ 'raw' => $this->make_docblock( array(
+ 'This is a function docblock.',
+ '',
+ 'This function is just a test, but we\'ve added this description anyway.',
+ '',
+ '@since 2.6.0',
+ '',
+ '@param string $var A string value.',
+ '@param int $num A number.',
+ '',
+ '@return bool Whether the function was called correctly.',
+ ) ),
+ 'summary' => 'This is a function docblock.',
+ 'raw_description' => 'This function is just a test, but we\'ve added this description anyway.',
+ 'description' => 'This function is just a test, but we\'ve added this description anyway.
',
'tags' => array(
array(
'name' => 'since',
@@ -114,8 +173,35 @@ public function test_function_docblocks() {
public function test_class_docblocks() {
$this->assertClassHasDocs(
- 'Test_Class'
- , array( 'description' => 'This is a class docblock.' )
+ 'Test_Class',
+ array(
+ 'raw' => $this->make_docblock( array(
+ 'This is a class docblock.',
+ '',
+ 'This is the more wordy description: This is a comment with two *\'s at the start,',
+ 'which means that it is a doc comment. Docblock comments are comment blocks used',
+ 'to document code. This one documents the Test_Class class.',
+ '',
+ '@since 3.5.2',
+ ) ),
+ 'summary' => 'This is a class docblock.',
+ 'description' => $this->multiline_string( array(
+ 'This is the more wordy description: This is a comment with two *\'s at the start,',
+ 'which means that it is a doc comment. Docblock comments are comment blocks used',
+ 'to document code. This one documents the Test_Class class.
',
+ ) ),
+ 'raw_description' => $this->multiline_string( array(
+ 'This is the more wordy description: This is a comment with two *\'s at the start,',
+ 'which means that it is a doc comment. Docblock comments are comment blocks used',
+ 'to document code. This one documents the Test_Class class.',
+ ) ),
+ 'tags' => array(
+ array(
+ 'name' => 'since',
+ 'content' => '3.5.2',
+ )
+ )
+ )
);
}
@@ -125,9 +211,44 @@ public function test_class_docblocks() {
public function test_method_docblocks() {
$this->assertMethodHasDocs(
- 'Test_Class'
- , 'test_method'
- , array( 'description' => 'This is a method docblock.' )
+ 'Test_Class',
+ 'test_method',
+ array(
+ 'raw' => $this->make_docblock( array(
+ 'This is a method docblock.',
+ '',
+ '@since 4.5.0',
+ '',
+ '@param mixed $var A parameter.',
+ '@param array $arr Another parameter.',
+ '',
+ '@return mixed The first param.',
+ ), "\t" ),
+ 'summary' => 'This is a method docblock.',
+ 'tags' => array(
+ array(
+ 'name' => 'since',
+ 'content' => '4.5.0',
+ ),
+ array(
+ 'name' => 'param',
+ 'types' => array( 'mixed' ),
+ 'variable' => '$var',
+ 'content' => 'A parameter.',
+ ),
+ array(
+ 'name' => 'param',
+ 'types' => array( 'array' ),
+ 'variable' => '$arr',
+ 'content' => 'Another parameter.'
+ ),
+ array(
+ 'name' => 'return',
+ 'types' => array( 'mixed' ),
+ 'content' => 'The first param.'
+ ),
+ ),
+ )
);
}
@@ -137,9 +258,11 @@ public function test_method_docblocks() {
public function test_property_docblocks() {
$this->assertPropertyHasDocs(
- 'Test_Class'
- , '$a_string'
- , array( 'description' => 'This is a docblock for a class property.' )
+ 'Test_Class',
+ '$a_string',
+ array(
+ 'summary' => 'This is a docblock for a class property.'
+ )
);
}
}