[JackPGreen]

For angle braces (</>) to be rendered correctly by Modello, they must be escaped by their HTML equivalents and then places inside a CDATA block, e.g.:

maven/maven-settings/src/main/mdo/settings.mdo

Lines 424 to 427 in f6a0120

	<description>
	<![CDATA[
	The <code>&lt;proxy&gt;</code> element contains informations required to a proxy settings.
	]]></description>

However, not all are like this - which causes them to be rendered incorrectly:

Updated all </> Modello usages to resolve:

Fixes: #13675

• I hereby declare this contribution to be licensed under the Apache License Version 2.0, January 2004

[gnodet-bot]

Nit: maven.mdo now has inconsistent > escaping — this new line uses <project> (both brackets HTML-escaped), while several existing descriptions in the same file use only < with a raw > (e.g. <build>, <scm>, <plugin>, <groupId>:<artifactId>:<version>). Worth aligning across the file for consistency, but not a blocker.

This review was generated by an AI agent, Hermès on behalf of @gnodet.

[gnodet-bot]

💡 Nit: This line uses <project> (both angle brackets HTML-escaped), but other descriptions in this file use <build>, <scm>, <plugin>, etc. — only < is escaped, > is raw. Worth picking one convention and applying it consistently across all description blocks.

[gnodet]

The build fails because of incomplete escaping in maven.mdo. Several descriptions were wrapped in CDATA blocks but still contain the half-escaped form <name> (opening < escaped, closing > raw).

Inside a CDATA block the XML parser passes content verbatim — < is not decoded, so Modello's javadoc generator emits the literal string <name> into the generated Java class's Javadoc comment. Javadoc then sees <name> as an unknown HTML element and rejects it with error: unexpected content on the generated ModelBase.java (lines 72 and 180) and Mixin.java (empty comment warning).

For example, in maven.mdo the properties field description:

The format is {@code <name>value</name>}.

Inside CDATA this should be either:

• {@code <name>value</name>} — both brackets escaped, OR
• {@code <name>value</name>} — raw angle brackets (CDATA protects them at the XML level, and {@code} protects them at the Javadoc level)

The same half-escaped pattern likely appears in all the descriptions touched in this PR. Please audit every <...> (where > is unescaped) within the newly added CDATA blocks and fix the escaping consistently.

[JackPGreen]

Nit: maven.mdo now has inconsistent > escaping — this new line uses <project> (both brackets HTML-escaped), while several existing descriptions in the same file use only < with a raw > (e.g. <build>, <scm>, <plugin>, <groupId>:<artifactId>:<version>).

This isn't new, e.g.:

maven/api/maven-api-model/src/main/mdo/maven.mdo

Line 3151 in f387510

<p>When a profile is activated and defines properties (via {@code &lt;properties&gt;}),

But I think this change just exposes the issue.

Please audit every <...> (where > is unescaped) within the newly added CDATA blocks and fix the escaping consistently.

Audited using AI-generated command:

% find . -type f -name '*.mdo' -exec perl -0777 -ne '
    while (/<!\[CDATA\[(.*?)\]\]>/sg) {
        $block = $1;
        $start = $-[0];

        $line = 1 + (substr($_, 0, $start) =~ tr/\n/\n/);

        @lines = split /\n/, $block, -1;
        for ($i = 0; $i < @lines; $i++) {
            print "$ARGV:" . ($line + $i) . ": $lines[$i]\n"
                if $lines[$i] =~ /[<>]/ && $lines[$i] =~ /&(?:lt|gt);/;
        }
    }
' {} +

Fixed in fcbc1eb.

I was not able to reproduce this failure locally (e.g. mvn package site -DskipTests completes unexceptionally) to validate further, so 🤞 for CI result.

[slachiewicz]

maybe this shoudl be fixed in Modello?

[JackPGreen]

I was not able to reproduce this failure locally (e.g. mvn package site -DskipTests completes unexceptionally) to validate further, so 🤞 for CI result.

CI failed, maybe this is the wrong solution after all.

maybe this shoudl be fixed in Modello?

I wasn't able to validate if it was a bug or a misconfiguration.

[elharo]

Something's seriously off here, maybe Modello? The greater than sign can be but DOES NOT HAVE TO BE escaped in XML.

[elharo]

Something is absolutely broken. The way this is structured It is requesting literal amspersands in the output, not less than and greater than signs.

[gnodet]

Thanks for the investigation! After tracing the full rendering pipeline I've found that the root cause is in Modello's xdoc generator, not in the .mdo descriptions. The .mdo files are correct as written.

Root cause trace:

1. MXParser reads <description> outside CDATA and XML-decodes < → <, so {@code <activation>} becomes the string {@code <activation>}.
2. XdocGenerator.rewrite() passes this to the chhorz javadoc-parser which wraps {@code X} in <code>X</code> without HTML-escaping X → produces <code><activation></code>.
3. Jsoup (XML output mode) treats <activation> as an unknown HTML element and silently drops it.

Fix: I've opened a PR against Modello to pre-process {@code} / {@literal} tags and HTML-escape their content before the parser+Jsoup pipeline: codehaus-plexus/modello#619

This PR (wrapping in CDATA + double-escaping) is not the right approach — it adds complexity and changes the semantics of the descriptions without addressing the underlying Modello bug. Once Modello 2.8.2 ships with the fix, the Maven site will render correctly without any changes here.

I'll close this PR in favour of the upstream Modello fix.

[gnodet]

Closing in favour of the upstream Modello fix: codehaus-plexus/modello#619