[Misc] Document why SonarQube java:S5785 must not be applied to the equals() contract tests

[claude]

Follow-up to #389, which took the opposite approach and was rightly closed after @michitux's review.

The 30 java:S5785 issues in xwiki-rendering all sit in hand-written equals()/hashCode() contract
tests. Converting assertTrue(a.equals(b)) to assertEquals(a, b) there is a bad idea, as the review
pointed out: the boolean form is what makes it visible at the call site which object is the receiver and
what argument it gets. So instead of changing the assertions — and instead of just marking the issues
"accepted" in SonarCloud, where the reasoning is invisible to anyone reading the test — this PR records
the reason in the code, per the
SonarQube section of the Java Code Style.

Change

@SuppressWarnings("java:S5785"), preceded by an explanatory comment, on the 6 concerned test methods:

Module	Test method	Issues covered
xwiki-rendering-api	ResourceReferenceTest#testEquals	3
xwiki-rendering-api	SyntaxTest#nonEquality	2
xwiki-rendering-api	SyntaxTypeTest#equalityAndInequality	2
xwiki-rendering-transformation-linkchecker	LinkStateTest#testEquals	4
xwiki-rendering-transformation-macro	MacroIdTest#testEquality	14
xwiki-rendering-transformation-macro	MacroContentSourceReferenceTest#equals	5

No assertion is modified — the test code is byte-for-byte what is on master today, plus the comment
and the annotation.

The explanation also names the specific trap, so the next person has the full picture: JUnit's
assertEquals/assertNotEquals go through AssertionUtils.objectsAreEqual(a, b)
(a == null ? b == null : a.equals(b)), so a receiver-first conversion would in fact still call the
original equals — but nothing at the call site says so, and SonarQube's java:S3415 ("swap these 2
arguments") would later push someone to reverse the order, at which point the contract silently stops
being tested.

The annotations are scoped to the method rather than the class so the rest of each test class stays
covered by the rule.

There is precedent for exactly this pattern in xwiki-platform: RegexEntityReferenceTest carries
@SuppressWarnings("java:S3415") with a comment explaining the same asymmetric-equals hazard.

Notes

• Test code only, no production change.
• Verified with mvn clean install -Plegacy,quality (Checkstyle, Revapi, JaCoCo and the unit tests) on
  the 3 affected modules.
• The corresponding SonarCloud issues have been re-opened (they were previously marked accepted); they
  will close on the next analysis once this lands, with the reason now living in the code.

Related

Other repos from the same sweep, unaffected by this discussion:

• xwiki-platform: [Misc] Fix 48 SonarCloud issues in various modules xwiki-platform#5993
• xwiki-commons: [Misc] Fix 28 SonarCloud issues in various modules xwiki-commons#1852

---

Generated by Claude Code