The javadoc for java.time.Duration has several comments that appear to have been copied from java.time.Period without making all the necessary updates. For example, in Duration.between, "The result of this method can be a negative period if the end is before the start." Since the API is careful elsewhere to distinguish between physical-time "duration" and civil-time "period", this is misleading.