PUBLIC OBJECT

HTML-formatting Javadocs

Public APIs

I work on lots of public APIs. For those, it's nice to have nicely-formatted Javadoc, following the Guava guidelines. This means lots of <p> tags, {@code} blocks! Here's an example from Okio:

  /**
   * Wait at most {@code timeout} time before aborting
   * an operation. Using a per-operation timeout means
   * that as long as forward progress is being made, no
   * sequence of operations will fail.
   *
   * <p>If {@code timeout == 0}, operations will run
   * indefinitely. (Operating system timeouts may still
   * apply.)
   */
  public Timeout timeout(long timeout, TimeUnit unit) {
    ...
  }

Private Implementations

I also work on a large, not-open-source Java project: the Square Cash service. This project is developed by a team, and quite frequently I've been harassing my team to fix their darn Javadoc tags. Typically it's a missing <p> tag. Here's an offending example from our payment history query:

  /**
   * Returns payments for `customerId` in the named role
   * with the current client. We query senders and recipients
   * independently and merge the results in memory because
   * MySQL uses its indices this way and doesn't otherwise.
   *
   * This returns one more results than `maxResults` so the
   * caller can tell if another page should be offered.
   */
  List<PaymentRow> paymentsInRole(Session session, Role role) {
     ...
  }

As it turns out, we never actually generate Javadoc for this codebase. So the little <p> tags never get exercised, and our source code is a little less legible than it would be otherwise.

The team had a vote. HTML formatting for code documentation is dumb, and we're not doing it anymore. Hopefully this leads to better documentation!