[
https://issues.apache.org/jira/browse/UNOMI-960?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Serge Huber reassigned UNOMI-960:
---------------------------------
Assignee: Serge Huber
> Public API Javadoc has missing comments and inconsistencies
> -----------------------------------------------------------
>
> Key: UNOMI-960
> URL: https://issues.apache.org/jira/browse/UNOMI-960
> Project: Apache Unomi
> Issue Type: Sub-task
> Reporter: Serge Huber
> Assignee: Serge Huber
> Priority: Major
>
> h2. Summary
> Developers and integrators rely on generated API documentation, but parts of
> the Unomi 3.x codebase still have missing, outdated, or inconsistent Javadoc.
> That makes the published API harder to read and hides gaps until someone runs
> a full documentation build.
> h2. What is going wrong today
> * Several public types and methods lack Javadoc comments or have incomplete
> parameter and return descriptions.
> * Some documentation-only improvements from the 3.x integration branch were
> deferred during backport work (for example scheduler task types and segment
> validation exceptions).
> * A full Javadoc build still reports many *no comment* warnings in modules
> such as the health check extension, even when doclint does not fail the build.
> * Contributors cannot always tell which doc gaps are intentional deferrals
> versus oversights left after large merges.
> h2. Impact
> * Harder onboarding for new contributors reading the API module and
> REST-facing types.
> * Published API docs on the project site may omit or misdescribe behavior
> operators depend on.
> * Release hygiene risk: doc problems may accumulate until CI or a manual
> {{build.sh --javadoc}} run surfaces them late in the cycle.
> h2. Who is affected
> * Developers maintaining the API, services, and extensions
> * Technical writers and release managers preparing 3.1.x documentation
> * Integrators using generated Javadoc or manual derived from it
> h2. What good would look like
> * Running {{mvn javadoc:javadoc}} (or {{build.sh --javadoc}}) on {{master}}
> completes without doclint *errors* on the modules in scope.
> * High-visibility public API types have complete class and method
> documentation, including {{@param}} and {{@return}} where required.
> * Known deferred 3-dev documentation deltas are either merged or explicitly
> recorded as out of scope with a short rationale.
> * Remaining warning-only gaps are reduced to an agreed baseline, or tracked
> as follow-ups with module-level acceptance notes.
> {panel:title=Local tracking|borderStyle=solid}
> Tracked locally as *PR 10* under
> [UNOMI-875|https://issues.apache.org/jira/browse/UNOMI-875] (post PR9 / 3-dev
> closure).
> {panel}
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
