# Share Javadoc — Publish API Docs Without Standing Up a Server

Canonical: https://commareports.com/share-javadoc
Published: 2026-08-29

> Javadoc builds a directory nobody outside your build can open. Publish it to a URL for a branch, an internal library, or a partner — with comments anchored to the class that needs a better doc.

# 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

```bash
./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](https://commareports.com/):

- `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

```bash
./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](/docs/api) and
[publishing from CI](/docs/ci).

`PATCH`ing 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/sharing).

## 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](/comment-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 →](https://commareports.com/)**

### Related

- [Share TypeDoc output](/share-typedoc) · [Share Sphinx docs](/share-sphinx-docs)
- [Share OpenAPI docs](/share-openapi-docs) · [Share a MkDocs site](/share-mkdocs-site)
- [Share a Gradle test report](/share-gradle-test-report) · [Share a JaCoCo report](/share-jacoco-report)
- [GitHub Pages alternatives](/alternatives/github-pages-alternatives)