docs/generating-documentation#109
Merged
Merged
Conversation
The project had no way to produce Java API documentation: no plugin, no
target, no CI step. maven-javadoc-plugin now renders the /** */ comments
to browsable HTML in target/reports/apidocs, reachable through a new
"make javadoc" target.
The plugin declares no executions, so it stays inert during a normal
build (verified: package never invokes it) and runs only when asked.
doclint is set to "all,-missing": it validates the syntax, the HTML, and
the {@link} references, but does not complain about missing @param or
@return, because Checkstyle already reports missing Javadoc
(MissingJavadocType, MissingJavadocMethod) and ADR-0011 keeps those
quality checks advisory rather than blocking.
Javadoc reads the source, so the accessors Lombok generates do not
appear in the output; delombok is deliberately not added.
The Lint workflow now also generates the API reference and publishes it next to the Checkstyle report: https://www.ericbouchut.com/learn-dev/ lists both, under /javadoc/ and /checkstyle/. The Javadoc rides along in this workflow on purpose rather than in one of its own: GitHub Pages serves a single site artifact, so a second workflow deploying Pages would clobber the Checkstyle report. Both reports are written to target/reports, so the assembly step lifts apidocs out first and only then copies what remains as the Checkstyle site; the checkstyle-report artifact excludes apidocs for the same reason. The job keeps continue-on-error, so a Javadoc failure can never gate a merge, and the root index becomes a small landing page listing both reports instead of redirecting to the only one there used to be.
The "Generating the Documentation" section held only a TODO. It now separates the hand-written documentation (README, ARCHITECTURE, ADRs, glossaries, RGAA, plans) from the generated one, and tabulates the four generated artefacts with the command and the output path of each. Two of them get a subsection, in the Locally/Online/On CI shape the Checkstyle and JaCoCo sections already use: the API reference, with what it contains, the absent Lombok accessors, and why Javadoc does not police missing comments (Checkstyle does); and the Merise diagrams, with their prerequisites, the generated-do-not-edit rule, and the schema drift check. The Checkstyle and JaCoCo reports are cross-linked instead of described twice. The "Code Documentation" placeholder no longer claims the code reference is unavailable: it points at the published Javadoc, as does the README documentation list.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## dev #109 +/- ##
=========================================
Coverage 80.33% 80.33%
Complexity 186 186
=========================================
Files 38 38
Lines 783 783
Branches 42 42
=========================================
Hits 629 629
Misses 124 124
Partials 30 30 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
ebouchut
added
documentation
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.
This PR adds the Maven Javadoc plugin (
maven-javadoc-plugin) to generate Javadoc documentation for the backend.This generates the Java API reference (
target/reports/api) and a "make javadoc" target.Note
Although the backend does not currently expose an API, this is in preparation for version 2, which will provide a REST API to handle React requests.
lintworkflow) to build and publish Javadoc to GitHub Pages alongside the Checkstyle report, with assembly to avoid clobber andcontinue-on-errorso Javadoc failures don't block merges.READMElinks to published javadoc.