[rys888]

Related to LANG-1341.

The class-level EqualsBuilder example calls appendSuper(super.equals(obj)) unconditionally. For a class whose superclass uses Object.equals, this compares identity and makes distinct instances unequal even when all their fields match.

This documentation-only change removes that call from the general example and explains when to include superclass equality, both after the example and in appendSuper(boolean)'s Javadoc. No runtime code or imports change.

The earlier PR #343 was closed for lack of follow-up. This addresses its remaining review request to explain Object.equals in the method documentation as well.

Validation (JDK 21, Maven 3.9.16):

• The full default Maven goals passed: 92,172 tests, 0 failures, 0 errors, 18 skipped, plus RAT, Checkstyle, japicmp, SpotBugs, PMD and Javadoc.
• Command: mvn -B -ntp -U -s ../commons-lang-LANG-1341-validation/maven-settings.xml. The temporary settings file only points the existing mirror at Maven Central. The initial run with the local mirror failed to obtain the parent site descriptor and stopped while rendering the PMD report (skin cannot be null); no project configuration was changed and no checks were skipped.
• Extracted and compiled the corrected example locally with Java 8 targeting: distinct instances with equal fields compare equal; identity, null and unrelated-class checks also pass. No additional upstream tests are needed for this documentation-only change.

Checklist:

• Read the contribution guidelines.
• Read the ASF Generative Tooling Guidance.
• AI assistance: OpenAI Codex helped inspect the issue and prior discussion, draft the documentation, and run validation. This is an AI-assisted contribution.
• Run a successful build using the default Maven goals.
• Behavioral tests: not applicable; no runtime behavior changes. Existing tests pass.
• Provide a description of what changes and why.
• Use a meaningful commit subject and body, including an Assisted-By trailer.

Review follow-up (2026-11-01): Removed the changes.xml entry as requested. The PR remains a draft pending review of LANG-1341 and alignment between the implementation and Javadoc. The follow-up passed the documented non-test checks on JDK 21: mvn -B -ntp -DskipTests -DskipITs -s ../commons-lang-LANG-1341-validation/maven-settings.xml. Tests were skipped in this follow-up run; the full test results above describe the original submission.

[garydgregory]

Do not edit this file.

[garydgregory]

Setting to draft. The Jira needs review to see how code and Javadoc should sync up.

[garydgregory]

@rys888

Thank you for the PR and addressing LANG-1341. The PR is basically correct but the text needs to be more precise.

I addressed this in commit a0b7121. You are credited in changes.xml.

Notes:

• “The superclass overrides” leaves inherited overrides implicit. The guidance should explicitly cover an equals(Object) implementation inherited from an ancestor.
• “Makes this builder return false” should identify isEquals(), since appendSuper() itself returns the builder.
• The method documentation should explain both boolean cases: false makes the equality result false, while true preserves the current result, including an existing false result.
• The warning should explain when to omit identity comparison when implementing field-based equality.

The PR identifies the right problem, but I wanted the resulting documentation to give users explicit usage guidance and an accurate description of the method’s behavior. The commit supersedes this PR; no runtime implementation change was needed.

Closing PR.