JinwooHwang opened a new pull request, #7926:
URL: https://github.com/apache/geode/pull/7926
# Java Documentation Modernization: Stable Aggregation, Legacy Tomcat
Neutralization, and Compliance Readiness
## Summary
This pull request restores and stabilizes the aggregate Javadoc build
(`:geode-assembly:docs`) under Gradle 7 by:
- Adding an isolated `javadocStubs` source set containing minimal legacy
Tomcat API placeholders.
- Replacing earlier brittle workarounds (class exclusions, legacy
extraction reliance) with a stable classpath-only symbol resolution strategy.
- Resolving missing symbols (`LifecycleSupport`, `SerializablePrincipal`,
etc.) **without** bundling obsolete Tomcat 6/7 artifacts.
Result: The aggregate Javadoc builds cleanly, includes intended Geode
modules, excludes unwanted external Tomcat API docs, and is positioned for
later enforcement hardening.
## Motivation
Previously the aggregate Javadoc failed due to unresolved Tomcat 6/7 symbols
after refactoring. Pulling the Tomcat 6 distribution to recover those types was
brittle and noisy. Excluding affected Geode sources reduced failures but
degraded documentation coverage.
Goals addressed:
1. Eliminate cross-project configuration resolution warnings.
2. Avoid globally disabling Javadoc error handling (`failOnError=false`).
3. Keep session-related sources in the docs.
4. Prevent Tomcat API packages from appearing in published output.
5. Preserve a path to future strict `-Xwerror` enforcement.
6. Remain RAT (license header) compliant.
## Key Changes
### Build (`geode-assembly/build.gradle`)
- Added `sourceSets { javadocStubs { ... } }`.
- Added stub output to the Javadoc classpath only (not published, not
runtime).
- Added exclusion: `exclude 'org/apache/catalina/**'`.
- Retained combined option: `options.addStringOption('Xwerror','-quiet')`.
### Stub Classes (with ASF headers)
Located under:
`geode-assembly/src/javadocStubs/java/`
- `org.apache.catalina.util.LifecycleSupport`
- `org.apache.catalina.ha.session.SerializablePrincipal`
- Supporting minimal placeholders:
- `org.apache.catalina.LifecycleListener`
- `org.apache.catalina.Realm`
- `org.apache.catalina.realm.GenericPrincipal`
They intentionally contain only the signatures required for symbol
resolution.
### Javadoc Assembly
- Aggregates sources from all `javadocOnly` dependency projects.
- Uses modern Tomcat 9 + annotations for compilation context.
- Excludes third-party Tomcat API docs while keeping Geode integration code
visible.
## Rationale
| Concern | Decision | Reason |
|---------|----------|--------|
| Legacy Tomcat symbols missing | Provide minimal stubs | Avoid
shipping/maintaining obsolete binaries |
| Third-party API leakage | Exclude `org.apache.catalina.*` | Keep published
API surface focused |
| Future strictness | Keep structural `-Xwerror` | Simple toggle later |
| License compliance | ASF headers on new sources | RAT passes cleanly |
## Verification
Performed:
1. Ran `:geode-assembly:docs`.
2. Confirmed generated HTML javadocs.
3. RAT task succeeded.
4. Session-related classes referencing Tomcat types appear in docs without
unresolved symbol warnings.
<!-- In order to streamline the review of the contribution we ask you
to ensure the following steps have been taken:
-->
### For all changes:
- [ ] Is there a JIRA ticket associated with this PR? Is it referenced in
the commit message?
- [x] Has your PR been rebased against the latest commit within the target
branch (typically `develop`)?
- [ ] Is your initial contribution a single, squashed commit?
- [x] Does `gradlew build` run cleanly?
- [ ] Have you written or updated unit tests to verify your changes?
- [ ] If adding new dependencies to the code, are these dependencies
licensed in a way that is compatible for inclusion under [ASF
2.0](http://www.apache.org/legal/resolved.html#category-a)?
<!-- Note:
Please ensure that once the PR is submitted, check Concourse for build
issues and
submit an update to your PR as soon as possible. If you need help, please
send an
email to [email protected].
-->
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
