Skip to content

Enforce Javadoc presence on public/protected methods once the Xtend-to-Java migration completes #1466

Description

@joaodinissf

The checkstyle configuration validates Javadoc content (JavadocMethod: @param/@return/@throws) but has never enforced Javadoc presenceMissingJavadocMethod is absent from avaloq.xml, so an entirely undocumented public method passes clean. This gap is as old as the configuration.

#1442 prototyped the fix: MissingJavadocMethod with scope="protected", tokens="METHOD_DEF" (constructors excluded), allowMissingPropertyJavadoc="true" (trivial accessors exempt), @Override/@Inject exempt — plus documentation for every method the rule surfaced at the time.

Why this is deferred: checkstyle only scans .java files, so undocumented API in .xtend sources is invisible to it. The ongoing Xtend-to-Java migration therefore exposes pre-existing undocumented API wave by wave — enabling the rule mid-campaign goes red after every merged migration (observed: 123 violations across four migrated modules, measured empirically on current master). The documentation written so far is being merged separately (see #1442); the rule enablement belongs after the last migration merges, against a stable surface.

When the migration completes:

  1. Run full-reactor checkstyle:check with the rule enabled → authoritative list of remaining undocumented public/protected methods.
  2. Document them per the established discipline: one-sentence summary derived from the signature/obvious behaviour, plus the tags the content rules require — no speculation, no name-restatement (example in docs: add Javadoc to public and protected API #1442's description).
  3. Enable the rule in ddk-configuration/checkstyle/avaloq.xml in the same PR, so the enabling commit is green.

Blocked by the completion of the Xtend-to-Java migration (tracked by the remaining refactor: migrate Xtend to Java - * PRs).

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions