Code reference theme corrupts generic parameter types

[sirreal]

The wp_ai_client_prompt() page renders PHPDoc types containing < and > as HTML instead of text.

Actual

• The title drops generic contents, reducing the types to ...|list|list|null.
• The Parameters section displays escaped generated markup and curly quotes.

Cause

• DevHub\get_signature() inserts parameter types unescaped before calling wp_kses_post(), so KSES treats generic syntax as tags.
• DevHub\get_params() uses each raw type as both a CSS class and HTML content, producing malformed markup for types containing < or >.

Expected

Type expressions should be rendered as text, with generic delimiters serialized as < and >. Raw type expressions should not be used as class attributes.

Acceptance criteria

• The complete generic type is visible in the title and Parameters section.
• No visible text contains generated <span class=... fragments or smart quotes.
• Existing type links and styling continue to work.

Related

WordPress/phpdoc-parser#270

[sirreal]

@westonruter for awareness. Currently the more advanced types are broken in documentation. I haven't found time to fix this yet, but since we're adding more advanced types, it would be very good to fix this before 7.2 is released.

[westonruter]

@sirreal I see it in the source:

 * @param string|MessagePart|Message|array|list<string|MessagePart|array>|list<Message>|null $prompt Optional. Initial prompt content.
 *                                                                                                   A string for simple text prompts,
 *                                                                                                   a MessagePart or Message object for
 *                                                                                                   structured content, an array for a
 *                                                                                                   message array shape, or a list of
 *                                                                                                   parts or messages for multi-turn
 *                                                                                                   conversations. Default null.

This seems due to the function “violating” the practice of reserving PHPStan's richer types to @phpstan-prefixed tags. We could work around this by changing the docblock to:

 * @param string|MessagePart|Message|array|null $prompt Optional. Initial prompt content.
 *                                                      A string for simple text prompts,
 *                                                      a MessagePart or Message object for
 *                                                      structured content, an array for a
 *                                                      message array shape, or a list of
 *                                                      parts or messages for multi-turn
 *                                                      conversations. Default null.
 * @return WP_AI_Client_Prompt_Builder The prompt builder instance.
 *
 * @phpstan-param string|MessagePart|Message|array|list<string|MessagePart|array>|list<Message>|null $prompt

However, it would be ideal if we didn't have to always do this at some point in the future. I know @johnbillion intends to write a proposal to allow the full PHPStan type system to be used in generic PHPDoc tags, but support from the Code Reference is a prereq for that (as seen here!)

Nevertheless, if the parsing issue is due here to list<string|MessagePart|array> then it would seem to also be an issue with more standard PHPDoc used in core, like array<string>. Indeed, I see another parsing issue for wp_localize_script() at https://developer.wordpress.org/reference/functions/wp_localize_script/

The docblock for that function includes:

 * @param array<string, mixed> $l10n        The data itself. The data can be either a single or multi-dimensional array.

This isn't a particularly “advanced” type.

---

Aside: It seems the code reference is attempting to convert MessagePart into WordPress\AiClient\Messages\DTO\MessagePart but it is coming through as WordPressAiClientMessagesDTOMessagePart. A separate issue.