docs: add Javadoc to public and protected API

[joaodinissf]

What

Documents the public and protected methods that a MissingJavadocMethod audit surfaced — 51 methods across 21 files, grouped into four area commits (check, checkcfg, xtext, samples). The diff is pure additions (+327, 0 deletions): only Javadoc comments; no code or signatures touched.

The audit rule itself (MissingJavadocMethod, public+protected, methods only, trivial-accessor and @Override/@Inject exemptions) is not enabled here — checkstyle cannot see .xtend files, so the ongoing Xtend-to-Java migration exposes previously-invisible undocumented API with every merged wave, and the gate would go red after each one. Enablement is deferred to #1466, after the migration completes.

How the docs were written

Each flagged method gets a simple, accurate Javadoc: a one-sentence summary plus the @param/@return/@throws tags the existing content rules require. Descriptions are terse and derived from the signature/obvious behaviour — no speculation, no boilerplate name-restatement. Example:

/**
 * Returns whether references held by the given object via the given feature should be indexed.
 *
 * @param from
 *          the object holding the reference
 * @param eReference
 *          the reference feature to test
 * @return {@code true} unless the reference is a containment or container reference
 */
protected boolean isIndexable(final EObject from, final EReference eReference) { ... }

Verification

• Full local gate (verify + checkstyle + pmd + cpd + spotbugs) green on current master.
• The added Javadoc is validated by the existing JavadocMethod content rules.

🤖 Generated with Claude Code

[rubenporras]

something is wrong in the CI/CD setup, we should enforce this with PMD or Checkstyle, in case you want to chase it further