Skip to content

Keep paragraphs and code blocks in ApiGen descriptions - #6849

Merged
ondrejmirtes merged 2 commits into
2.3.xfrom
apigen-paragraphs
Oct 26, 2026
Merged

ondrejmirtes merged 2 commits into
2.3.xfrom
apigen-paragraphs

Conversation

@ondrejmirtes

@ondrejmirtes ondrejmirtes commented Oct 26, 2026 •

Copy link
Copy Markdown
Member

Every description on apiref.phpstan.org rendered as one long paragraph, for example TrinaryLogic.

  1. Keep paragraphs apart. phpdoc-parser puts each paragraph into its own text node with an empty node in between. ApiGen dropped the empty nodes and joined the rest with a space. A small PhpDocResolver subclass keeps them as blank lines, and MarkdownConverter removes the spaces ApiGen's join adds around them. Lists, tables and code fences now render wherever they appear, not only at the start of a description. Namespace listings now show only the first paragraph as the short description, as ApiGen intends.
  2. Use code fences in class PHPDocs. phpdoc-parser trims the first line of a paragraph, so indented code samples could never render as code blocks. TrinaryLogic, Type (including the getTemplateType() example, which used a @-template workaround), TypeTraverser::map(), VerbosityLevel, GeneralizePrecision, AccessoryType and ContainerExtensionsExtension now use ```php fences.

Checked by generating the docs before and after. Both runs produce 1776 files. Descriptions have 7542 → 8381 <p> elements and 13 → 33 links. Raw ``` text no longer appears outside the source listing pages; before, 160 lines showed it, including existing fenced examples in other PHPDocs that were broken by the join. The <pre> blocks that disappeared were all on namespace index pages, which used to show each class's full description.

phpdoc-parser puts each paragraph of a PHPDoc into its own text node.
ApiGen dropped the empty nodes between them and joined the rest with a
space, so every description rendered as one paragraph. Lists, tables and
code fences that did not start the description were not recognized, and
short descriptions in namespace listings showed the whole text.

Amp-Thread-ID: https://ampcode.com/threads/T-01a176c6-528a-7430-b296-e66930d153b4
phpdoc-parser trims the first line of a paragraph, so indented code
samples lost the indentation that made them code blocks.

Amp-Thread-ID: https://ampcode.com/threads/T-01a176c6-528a-7430-b296-e66930d153b4
@ondrejmirtes
ondrejmirtes merged commit 83e5abe into 2.3.x Oct 26, 2026
602 checks passed
@ondrejmirtes
ondrejmirtes deleted the apigen-paragraphs branch October 26, 2026 08:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant