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!