[PR] UNOMI-960: Api Javadoc cleanup and pragmatic validation [unomi]

["sergehuber (via GitHub)" <gi...@apache.org>]

sergehuber opened a new pull request, #821:
URL: https://github.com/apache/unomi/pull/821

   ## Plain-language summary
   
   Published API documentation in the `api` module was often missing or too short. Integrators and extension authors had little help when reading types, services, and tenant APIs in Javadoc.
   
   This change improves Javadoc across the public and protected surface of `api`. It also sets a practical build policy: broken links and invalid comment HTML fail the build, while missing comments on private members are ignored. A separate warning-only check reports missing or wrong `@param` / `@return` tags on public and protected members.
   
   More modules can follow in later work; this PR focuses on `api` and the validation tooling.
   
   ## What changed
   
   * Expanded and fixed Javadoc in `api` (~90 Java files): class descriptions, service interfaces, query types, tenant types, and tag fixes (`@param`, `@return`, enum constants).
   * Configured `maven-javadoc-plugin` with `show=protected` and `doclint=all,-missing` so releases fail on broken references/HTML/syntax, not on every undocumented private field.
   * Added `config/checkstyle-javadoc.xml` and Maven profile `-Pjavadoc-tags-warn` for public/protected tag completeness (warnings only, does not fail the build).
   * Updated `build.sh --javadoc` (and `--ci`) to run doclint first, then the tag warning pass.
   
   ## Test plan
   
   - [x] `mvn -pl api javadoc:javadoc -DskipTests` — BUILD SUCCESS (no doclint errors)
   - [x] `mvn -pl api -Pjavadoc-tags-warn checkstyle:check` — 0 violations on `api`
   - [ ] CI on this PR
   
   ## References
   
   UNOMI-960


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@unomi.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] UNOMI-960: API Javadoc, manual docs, and validation tooling [unomi]

["sergehuber (via GitHub)" <gi...@apache.org>]

sergehuber merged PR #821:
URL: https://github.com/apache/unomi/pull/821


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: dev-unsubscribe@unomi.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org