Code reference: stop running wpautop over descriptions; render snippet source as a code block

[sirreal]

What trunk does

get_description() runs every reference description through the_content with wpautop() registered. The description is already complete HTML: phpdoc-parser renders it with Parsedown at import and then runs fix_newlines(), which turns a soft wrap after a sentence-ending . into a literal <br> and merges every other newline into a space. wpautop() has nothing left to do, so what it does is wrong:

• It wraps the [code lang="php"] shortcode text in <p>, and do_shortcode() then expands the shortcode inside that paragraph. 182 published posts serve <p> <pre class="wp-block-code">…</pre></p>. A <pre> start tag closes an open <p>, so browsers eject the code block and leave an empty paragraph.
• It wraps the parser's snippet placeholder comment in <p>, or leaves an unclosed <p> before one inside a list item, so <php-snippet> renders inside a paragraph.

Interactive snippets keep their PHP only in a <script type="application/x-php+json"> payload and build their UI in a shadow root. Read the page without running that module and there is no code anywhere in the document.

Changes

1. Stop running wpautop() over descriptions

get_description() removes wpautop around its one the_content call and restores it at whatever priority it held, the idiom already used for filter_code_content on the lines above. The shortcode and texturize passes still run.

Before, /reference/classes/wpdb/insert/:

<p>Examples:</p>
<p> <pre class="wp-block-code"><code lang="php" class="language-php line-numbers">$wpdb-&gt;insert(
…
);</code></pre></p>

After:

<p>Examples:</p> <pre class="wp-block-code"><code lang="php" class="language-php line-numbers">$wpdb-&gt;insert(
…
);</code></pre>

No <br> is removed and nothing reflows: the line breaks in descriptions are the parser's literal <br>, which wpautop() only respelled as <br />.

Each description is now served on one line. fix_newlines() collapsed the newlines and wpautop() was reinserting them around block tags. Rendering is identical; view-source is less readable (wpdb::prepare is 1,379 characters on one line).

Corpus

Every published parser post rendered both ways on the sandbox: 12,399 posts, 3,583 with a long description.

difference between trunk and this branch	posts
[code] shortcode <pre> contents differ	0
paragraphs that only wpautop() supplied	0
<br> respelled <br />, line breaks around block tags	3,397
[code] <pre> no longer wrapped in <p>	182
other	4

The 4: wp_check_php_mysql_versions and update_core (whitespace around nested lists), get_linkobjectsbyname (a raw <li> in prose, malformed either way), WP_Duotone::get_svg_definitions (a stray …… text node gains or loses a paragraph).

2. Render the snippet source as a code block

render_php_code_snippet() appends <pre class="wp-block-code"><code class="language-php"> holding the source inside <php-snippet>, after the payload.

Before:

<p><php-snippet><script type="application/x-php+json">"$processor = new …"</script></php-snippet></p>

After:

<php-snippet><script type="application/x-php+json">"$processor = new …"</script><pre class="wp-block-code"><code class="language-php">$processor = new …</code></pre></php-snippet>

The <p> is gone because of change 1, not this one. Without change 1 the <pre> would close that paragraph and the browser would move the code block out of the element.

The element's shadow root has no <slot>, so the block disappears once the element upgrades. It is for the reader whose browser never gets there, and for anything reading the HTML rather than executing it. Its text is byte-identical to the JSON payload, so the shown source and the run source cannot drift.

Decisions

• Remove the filter rather than steer around it. A <div> around <php-snippet> survives the ejection but leaves two empty paragraphs and the 182 broken pages. Converting the placeholder to a block element before wpautop() runs (a the_content filter at priority 9) avoids the empty paragraphs, couples the block to filter ordering, and leaves the 182. CSS to hide the ejected copy hides the fallback from the readers it exists for. Only removing the filter fixes the cause.
• set_modifiable_text() rather than esc_html(). esc_html() does not double-encode, so a literal <egg> in a snippet (the class_list() example has one) would pass through and the browser would show <egg>: the shown source would differ from the source that runs. The Tag Processor encodes for the text position it writes into. It only writes to a #text token, so the <code> element carries a placeholder for it to overwrite.
• Scope. get_description() has one caller, the code description block, on parser post types. Handbooks are untouched. The @see loop in the same file has an older unguarded remove_filter/add_filter pair for wpautop; it behaves the same at the default priority and is left alone here.
• Exception safety. No try/finally around the filter removal, matching the filter_code_content handling beside it.

Verifying

Read the served HTML (view-source or curl). DevTools shows the repaired tree, which hides the bug.

• /reference/classes/wp_html_tag_processor/class_list/: <php-snippet> at block level, <pre> inside it, no <p> touching it, and the <code> text decodes to exactly the JSON payload.
• /reference/classes/wpdb/insert/: <pre class="wp-block-code"> no longer inside <p>.
• /reference/functions/wp_insert_post/: curly quotes and autolinked references still present.
• Any snippet page with JavaScript disabled: the source is visible.

Risk and rollback

git revert, no reimport and no data change. Page caches serve the old markup until they expire.

Testing

No PHP test harness here, so manual:

• The corpus diff above, read-only and paced, on the sandbox.
• The branch deployed on the sandbox, served HTML read with curl: the three pages above hold, class_list carries the DocBlock's literal <egg> as <egg>, and wp_insert_post has the same curly-quote and autolink counts as production.
• set_modifiable_text() / get_modifiable_text() round trip against a real WP_HTML_Tag_Processor: <, >, &, quotes, a literal </code></pre><script>alert(1)</script>, heredocs, non-ASCII. All return the original string.
• The real filter chain (core WP_Hook, real wpautop(), both nested the_content passes) run locally with and without the change. Trunk produces <p><php-snippet>…</php-snippet></p>; this branch produces the markup above. Core's do_blocks() removes wpautop before the outer pass reaches priority 10, so the assembled page never goes through it again.
• Four placeholder shapes (own block, whole description, inside a list item, after a list) loaded in a browser against the real playground.wordpress.net/php-code-snippet.js: the <pre> is a child of <php-snippet> in each, hidden after upgrade, readable with the module blocked.

Written by Claude in Claude Code at my direction and reviewed by me; the parser, wpautop() and custom-element behaviour described here was measured, not assumed.