There are lots of things we might want to document about a method in an API. Historically we've framed them as either being "specification" (e.g., necessary postconditions) or "implementation notes" (e.g., hints that give the user an idea what's going on under the hood.) But really, there are four boxes (and we've been cramming them into two, or really 1.5):

 { API, implementation } x { specification, notes }

(We sometimes use the terms normative/informative to describe the difference between specification/notes.) Here are some descriptions of what belongs in each box.

1. API specification. This is the one we know and love; a description that applies equally to all valid implementations of the method, including preconditions, postconditions, etc.

2. API notes. Commentary, rationale, or examples pertaining to the API.

3. Implementation specification. This is where we say what it means to be a valid default implementation (or an overrideable implementation in a class), such as "throws UOE." Similarly this is where we'd describe what the default for putIfAbsent does. It is from this box that the would-be-implementer gets enough information to make a sensible decision as to whether or not to override.

4. Implementation notes. Informative notes about the implementation, such as performance characteristics that are specific to the implementation in this class in this JDK in this version, and might change. These things are allowed to vary across platforms, vendors and versions.

The proposal: add three new Javadoc tags, @apiNote, @implSpec, and @implNote. (The remaining box, API Spec, needs no new tag, since that's how Javadoc is used already.) @impl{spec,note} can apply equally well to a concrete method in a class or a default method in an interface.