使用jdk8 新的javadoc api 比如 @apiNote, @implSpec and @implNote

[venusdrogon]

使用jdk8 新的javadoc api 比如 @implSpec

https://blog.csdn.net/dnc8371/article/details/107265585

原文 https://www.javacodegeeks.com/2015/01/new-javadoc-tags-apinote-implspec-and-implnote.html

JDK广泛使用新标签。 一些例子：

ConcurrentMap ： 几个@implSpec定义默认实现的行为，例如在replaceAll 。 Objects使用@apiNote解释为什么添加了看似无用的方法isNull和nonNull 。 抽象类Clock在其类注释中使用@implSpec和@implNote来区分必须注意哪些实现以及如何实现现有方法。

The new Javadoc tags are explained pretty well in the feature request’s description (I changed the layout a little):

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.” 这就是我们所说的有效默认实现（或类中的可重写实现）的含义，例如“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.

类似地，我们将在这里描述putIfAbsent的默认功能。 正是从这个框中，未来的实现者获得了足够的信息，以便做出是否覆盖的明智决定。

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.

[venusdrogon]

public interface Lottery {

	/**
	 * Picks the winners from the specified set of players.
	 * <p>
	 * The returned list defines the order of the winners, where the first prize goes to the player at position 0. The
	 * list will not be null but can be empty.
	 *
	 * @apiNote This method was added after the interface was released in version 1.0. It is defined as a default method
	 *          for compatibility reasons. From version 2.0 on, the method will be abstract and all implementations of
	 *          this interface have to provide their own implementation of the method.
	 * @implSpec The default implementation will consider each player a winner and return them in an unspecified order.
	 * @implNote This implementation has linear runtime and does not filter out null players.
	 * @param players
	 *            the players from which the winners will be selected
	 * @return the (ordered) list of the players who won; the list will not contain duplicates
	 * @since 1.1
	 */
	default List<String> pickWinners(Set<String> players) {
		return new ArrayList<>(players);
	}

}

[venusdrogon]

maven 配置

https://github.com/nipafx/demo-javadoc-8-tags/blob/master/pom.xml?ts=4#L110-L133