UNOMI-960: API Javadoc, manual docs, and validation tooling#821
Merged
Conversation
Expand and fix public/protected Javadoc in the api module, configure doclint to fail only on broken links/HTML/syntax, and add a Checkstyle profile plus build.sh --javadoc two-pass checks for tag gaps on the published API surface.
sergehuber
changed the title
Improve Javadoc quality across api, rest, persistence-spi, services, and router modules: fix layout, remove script-style comments, restore field docs, and use fully qualified @link targets. Extend manual cross-links for scheduler, multitenancy, and whats-new; fix TenantRequest Javadoc.
Remove fictional 3.0 compatibility mode, align version pins and config keys with the codebase, update tenant/shell examples, expand whats-new and security chapters, and refresh root and module READMEs for 3.1.
Add a progressive conditions guide with PlantUML diagrams and REST examples. Document all built-in condition and action types in catalog tables, fix remaining 3.x doc gaps (anchors, query builder naming, healthcheck note, index structure).
Add a condition validation chapter, a debugging section in the conditions guide, and cross-links from whats-new and request tracing docs.
Fix stale examples (evaluator interfaces, query builder paths, feature names, POM artifacts), consolidate ES/OS guidance, document missing META-INF/cxs paths, and add cross-links to validation and samples.
Document DS as the required OSGi registration style for new plugins, replace Blueprint examples, and point readers at maintained modules instead of legacy samples/.
Replace Blueprint scheduler wiring with Declarative Services examples and state DS-first OSGi guidance in CLAUDE.md for contributors and agents.
sergehuber
changed the title
Use explicit [#id] section anchors for stable HTML/PDF cross-references, resolve duplicate IDs and PlantUML/table issues, and align PDF idseparator with underscore-based links so mvn clean install in manual builds cleanly.
…avigation Align the manual with unomi.apache.org (Inter, brand colors, hero cover, site nav/footer) and add responsive UX: burger nav plus bottom TOC sheet through 1023px, with desktop sidebar layout from 1024px.
…eview
Split merged comment lines that were rendering stray asterisks mid-sentence,
restore missing @ in several {@code}/{@link} tags, fix constructor/setter
indentation in two REST endpoints, clarify that TenantSecurityService isn't
actually wired into the OSGi runtime, and stop showing Blueprint-registered
built-in condition classes as if they used Declarative Services.
ProfileService#search(Query) doesn't exist (real signature takes a Class too), and PersistenceService's Query links weren't resolvable since the class isn't imported there. Both failed doclint's reference check.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Plain-language summary
Operators and developers had a hard time learning Unomi 3.1 from Javadoc and the user manual alone. Many public API comments were missing or unclear. The new background scheduler had no dedicated manual chapter. Condition types, validation rules, and plugin patterns were scattered or outdated.
This PR improves Javadoc on the published API surface, adds pragmatic doc checks to the build, and expands the manual with scheduler, conditions, validation, and plugin guides. It also fixes several 3.0/3.1 documentation errors (wrong version pins, fictional compat flags, incorrect shell examples).
What changed
Javadoc and build validation
api,tracing-api,common,scripting,router-api,services-common,persistence-spi,rest, and scheduler/tenant code inservices.-Pjavadoc-tags-warn.build.sh --javadocfor a two-pass doclint + tag-warning check.@Overrideannotations inParserHelperthat broke compile.Manual — new chapters and guides
scheduler.adoc— architecture, config, REST, shell, plugin patterns, metrics, troubleshooting (PlantUML diagrams).conditions-guide.adoc— progressive conditions tutorial with diagrams and REST examples.condition-validation.adoc— save-time condition parameter rules and error types.builtin-condition-types.adoc/builtin-action-types.adoc— full built-in type catalogs.writing-plugins.adocfor Unomi 3.1 (ES/OS split, correct feature names,META-INF/cxs/layout).scheduler.adoc,builtin-condition-types.adoc,CLAUDE.md).Manual — accuracy fixes
unomi.v3_0.compatibility.mode; align V2 compat property names.requestedId), shell CRUD examples, and multitenancy config keys.whats-new,security, GraphQL auth, and cross-links (tracing, conditions, debugging).Out of scope (follow-up)
servicesimpls andgraphql/cxs-impl(~hundreds of tag warnings remain).configuration.adoctosecurity.adoc.twitter-sample.adocBlueprint sections).Test plan
mvn -pl api -Pjavadoc-tags-warn checkstyle:check— 0 violationsmvn -pl persistence-spi,rest,services -Pjavadoc-tags-warn checkstyle:checkon cleaned packages — 0 violationsmvn -pl api javadoc:javadoc -DskipTests— passes with doclint./build.sh --javadoc --no-karaf— local pass./build.sh --javadoc— CI full passReferences
UNOMI-960, UNOMI-875