[
https://issues.apache.org/jira/browse/UNOMI-960?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Serge Huber updated UNOMI-960:
------------------------------
Description:
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.
was:
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}
> 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.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
