How do I share Javadoc without hosting a site?

Build it (`./gradlew javadoc` or `mvn javadoc:javadoc`) and drop the output directory into Comma. `index.html` becomes the report body and every class page, stylesheet and search script uploads alongside it, so the whole tree resolves at one URL with no server to run.

Where does the Javadoc output go?

Gradle writes it to `build/docs/javadoc/`; Maven's `javadoc:javadoc` goal writes to `target/site/apidocs/`. Both are directories — `index.html` plus per-package and per-class pages, `stylesheet.css`, and the search index — so upload the folder, not the single file.

Does the Javadoc search box still work?

Yes, for modern Javadoc output. The search relies on the `*-search-index.js` files shipped with the docs, which upload as assets alongside the pages, and scripts run inside the sandboxed iframe — so type-ahead search over classes and members keeps working at the published URL.

Why publish Javadoc for an internal library at all?

Because the consumers of an internal library are usually the people least able to build it. A URL per release, with per-report access limited to your domain, gives them the API surface without a Gradle install and without publishing your internals to the open web.

Can reviewers leave feedback on the docs?

Yes. Select a class or method description and leave an anchored thread — 'this doesn't say what happens on null' lands on the method it is about and survives the next docs build, which is a considerably better fate than the same sentence in a Slack channel.

Share Javadoc

Javadoc has one job and does it well. The awkward part is everything after: the output is a directory of a few thousand files that only exists inside build/, and the consumers of an internal library are precisely the people who don't have your build set up.

The usual answers are all heavier than the problem. Stand up a static site. Add a docs job to the deploy pipeline. Publish to an internal artifact server that nobody can find. Or — most often — don't, and answer the same three questions in Slack forever.

Build it

./gradlew javadoc         # → build/docs/javadoc/
# or
mvn javadoc:javadoc       # → target/site/apidocs/

Either way you get a directory:

build/docs/javadoc/
├── index.html
├── com/…/SomeClass.html   # one page per class
├── stylesheet.css
├── script.js
└── *-search-index.js

Drop the folder in

Drag build/docs/javadoc/ (or a zip of it) into Comma:

index.html becomes the report body — the page carrying the comment layer.
Every package and class page, the stylesheet and the search index upload alongside it, and relative href references are rewritten to the uploaded copies, so the frame navigation and the class links resolve.
Scripts run inside a sandboxed iframe (allow-scripts, no allow-same-origin), so modern Javadoc's type-ahead search keeps working — which is most of what makes the docs usable.

One URL. No server, no bucket, no DNS.

From the release job

./gradlew javadoc

curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html build/docs/javadoc/index.html \
        --arg title "API docs — $VERSION" \
        '{title: $title, html: $html}')"

The API is JSON-only, so the class pages go up through POST /api/v1/reports/$REPORT_ID/assets as base64 — one call per file, worth scripting once. See the API reference and publishing from CI.

PATCHing one saved id gives the library a permanent address whose content tracks the current release, and a revision history that is a readable record of how the public API actually changed — a better answer to "when did that method get deprecated?" than a git log over the whole module.

Internal doesn't have to mean public

Access is per report: private, your team, anyone signed in at your domain, or anyone with the link, with view / comment / edit rights. An internal platform library gets a domain-gated URL; a partner SDK gets a link-only one for the integration window. See sharing & access control.

Docs review, on the docs

The reason to put a comment layer on API documentation is that docs feedback is almost always specific and almost always lost. "This doesn't say what happens when the list is empty" is a useful sentence attached to the method, and noise in a channel.

Select the description, leave a thread, and it stays anchored to that method across docs builds — a standing queue of the exact places the Javadoc is thin. See commenting on HTML.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total. A large library's Javadoc can exceed 500 pages — publish the package summaries and the public API surface, or scope the task with -notree -noindex and an explicit package list.
Scripts run, sandboxed — no same-origin access.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Publish Javadoc →