[2.0 branch] Fix parsing of docblocks that contain code snippets (#5748)

* Fix parsing of docblocks that contain code snippets

* Add variable to docs for `amp_dev_mode_enabled` filter

* Wrap HTML tag in backticks

* Add more markdown formatting and restore linebreak

* Remove obsolete amp_is_canonical() examples

* Reorder composer.json fields

* Ensure alphabetical order for patches in composer.json

* Run composer update

Co-authored-by: Pierre Gordon <[email protected]>
Co-authored-by: John Watkins <[email protected]>

Author: 3 people

composer.json

@@ -45,16 +45,16 @@
   "extra": {
     "downloads": {
       "phpstan": {
-        "url": "https://github.com/phpstan/phpstan/releases/latest/download/phpstan.phar",
         "path": "vendor/bin/phpstan",
-        "type": "phar"
+        "type": "phar",
+        "url": "https://github.com/phpstan/phpstan/releases/latest/download/phpstan.phar"
       }
     },
     "patches": {
       "sabberworm/php-css-parser": {
-        "Add additional validation for size unit <https://github.com/sabberworm/PHP-CSS-Parser/pull/193>": "https://github.com/sabberworm/PHP-CSS-Parser/compare/3bc5ded67d77a52b81608cfc97f23b1bb0678e2f%5E...468da3441945e9c1bf402a3340b1d8326723f7d9.patch",
-        "Validate name-start code points for identifier <https://github.com/sabberworm/PHP-CSS-Parser/pull/185>": "https://github.com/sabberworm/PHP-CSS-Parser/compare/d42b64793f2edaffeb663c63e9de79069cdc0831%5E...113df5d55e94e21c6402021dfa959924941d4c29.patch",
-        "Fix parsing CSS selectors which contain commas <https://github.com/westonruter/PHP-CSS-Parser/pull/1>": "https://github.com/westonruter/PHP-CSS-Parser/compare/master...10a2501c119abafced3e4014aa3c0a3453a86f67.patch"
+        "1. Add additional validation for size unit <https://github.com/sabberworm/PHP-CSS-Parser/pull/193>": "https://github.com/sabberworm/PHP-CSS-Parser/compare/3bc5ded67d77a52b81608cfc97f23b1bb0678e2f%5E...468da3441945e9c1bf402a3340b1d8326723f7d9.patch",
+        "2. Validate name-start code points for identifier <https://github.com/sabberworm/PHP-CSS-Parser/pull/185>": "https://github.com/sabberworm/PHP-CSS-Parser/compare/d42b64793f2edaffeb663c63e9de79069cdc0831%5E...113df5d55e94e21c6402021dfa959924941d4c29.patch",
+        "3. Fix parsing CSS selectors which contain commas <https://github.com/westonruter/PHP-CSS-Parser/pull/1>": "https://github.com/westonruter/PHP-CSS-Parser/compare/master...10a2501c119abafced3e4014aa3c0a3453a86f67.patch"
       }
     }
   },

composer.lock

@@ -174,8 +174,8 @@ public function parse_files( $files, $root ) {
 	 *
 	 * This function fixes text by merging consecutive lines of text into a
 	 * single line. A special exception is made for text appearing in `<code>`
-	 * and `<pre>` tags, as newlines appearing in those tags are always
-	 * intentional.
+	 * and `<pre>` tags or wrapped in triple backticks (```), as newlines
+	 * appearing in those are always intentional.
 	 *
 	 * @param string $text Text for which to fix the newlines.
 	 *
@@ -194,6 +194,15 @@ static function ( $matches ) use ( $replacement_string ) {
 			$text
 		);
 
+		// Replace newline characters within triple backticks with replacement string.
+		$text = preg_replace_callback(
+			'/(?<=```)(.+)(?=```)/s',
+			static function ( $matches ) use ( $replacement_string ) {
+				return preg_replace( '/[\n\r]/', $replacement_string, $matches[1] );
+			},
+			$text
+		);
+
 		// Merge consecutive non-blank lines together by replacing the newlines with a space.
 		$text = preg_replace(
 			"/[\n\r](?!\s*[\n\r])/m",

docs/src/Parser/Parser.php

@@ -9,7 +9,7 @@
 ```
 
 {{# has_description }}
-{{ get_description }}
+{{{ get_description }}}
 
 {{/ has_description }}
 {{# has_arguments }}

docs/templates/function.mustache

@@ -325,42 +325,35 @@ function amp_correct_query_when_is_front_page( WP_Query $query ) {
  *
  * Themes can register support for this with `add_theme_support( AMP_Theme_Support::SLUG )`:
  *
- *      add_theme_support( AMP_Theme_Support::SLUG );
+ * ```php
+ * add_theme_support( AMP_Theme_Support::SLUG );
+ * ```
  *
  * This will serve templates in AMP-first, allowing you to use AMP components in your theme templates.
  * If you want to make available in transitional mode, where templates are served in AMP or non-AMP documents, do:
  *
- *      add_theme_support( AMP_Theme_Support::SLUG, array(
- *          'paired' => true,
- *      ) );
+ * ```php
+ * add_theme_support( AMP_Theme_Support::SLUG, array(
+ *     'paired' => true,
+ * ) );
+ * ```
  *
- * Transitional mode is also implied if you define a template_dir:
+ * Transitional mode is also implied if you define a `template_dir`:
  *
- *      add_theme_support( AMP_Theme_Support::SLUG, array(
- *          'template_dir' => 'amp',
- *      ) );
+ * ```php
+ * add_theme_support( AMP_Theme_Support::SLUG, array(
+ *     'template_dir' => 'amp',
+ * ) );
+ * ```
  *
  * If you want to have AMP-specific templates in addition to serving AMP-first, do:
  *
- *      add_theme_support( AMP_Theme_Support::SLUG, array(
- *          'paired'       => false,
- *          'template_dir' => 'amp',
- *      ) );
- *
- * If you want to force AMP to always be served on a given template, you can use the templates_supported arg,
- * for example to always serve the Category template in AMP:
- *
- *      add_theme_support( AMP_Theme_Support::SLUG, array(
- *          'templates_supported' => array(
- *              'is_category' => true,
- *          ),
- *      ) );
- *
- * Or if you want to force AMP to be used on all templates:
- *
- *      add_theme_support( AMP_Theme_Support::SLUG, array(
- *          'templates_supported' => 'all',
- *      ) );
+ * ```php
+ * add_theme_support( AMP_Theme_Support::SLUG, array(
+ *     'paired'       => false,
+ *     'template_dir' => 'amp',
+ * ) );
+ * ```
  *
  * @see AMP_Theme_Support::read_theme_support()
  * @return boolean Whether this is in AMP 'canonical' mode, that is whether it is AMP-first and there is not a separate (paired) AMP URL.
@@ -1450,7 +1443,7 @@ function amp_get_content_embed_handlers( $post = null ) {
 /**
  * Determine whether AMP dev mode is enabled.
  *
- * When enabled, the <html> element will get the data-ampdevmode attribute and the plugin will add the same attribute
+ * When enabled, the `<html>` element will get the data-ampdevmode attribute and the plugin will add the same attribute
  * to elements associated with the admin bar and other elements that are provided by the `amp_dev_mode_element_xpaths`
  * filter.
  *
@@ -1468,7 +1461,7 @@ function amp_is_dev_mode() {
 	 * queries for the expressions returned by the 'amp_dev_mode_element_xpaths' filter.
 	 *
 	 * @since 1.3
-	 * @param bool Whether AMP dev mode is enabled.
+	 * @param bool $is_dev_mode_enabled Whether AMP dev mode is enabled.
 	 */
 	return apply_filters(
 		'amp_dev_mode_enabled',