新的Javadoc标签@apiNote，@implSpec和@implNote

最新推荐文章于 2024-01-03 15:29:23 发布
原创 最新推荐文章于 2024-01-03 15:29:23 发布 · 8k 阅读 · 0 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#jdk

本文详细介绍了JDK中引入的一些新特性，包括并发地图的实现细节、对象类中有趣的方法注释以及抽象类Clock的实现规范说明。这些内容对于理解JDK内部工作原理及其最新改进具有重要意义。

摘要生成于 C知道 ，由 DeepSeek-R1 满血版支持， 前往体验 >

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

  • 并发地图：

    • 几个@implSpec定义了默认实现的行为，例如 replaceAll。 

    • 有趣的@impl注意 getOrDefault和 forEach。 

    • 重复@impl注意在Map中默认实现的抽象方法，记录“本实施方案有意地重新提取Map中提供的不正确的默认值”，例如 替换。 

  • 对象使用@apiNote解释为什么看似无用的方法的isNull和非空加。 

  • 抽象类Clock在其类注释中使用@implSpec和@implNote来区分必须注意的实现以及现有方法的实现方式。 


使用新的Javadoc标签@apiNote、@implSpec和@implNote在编写RESTful API文档时的最佳实践
JipForth的博客
09-21 508
综上所述，通过使用新的Javadoc标签@apiNote、@implSpec和@implNote，开发人员可以更好地编写RESTful API文档。为了提供更好的文档支持，Java SE 8中引入了一些新的Javadoc标签，其中包括@apiNote、@implSpec和@implNote。在上面的示例中，使用@implNote标签提供了有关发送电子邮件API实现的额外说明和注意事项。在上面的示例中，使用@implSpec标签提供了有关计算两个数字之和的API实现规范的说明。
@apinote_新的Javadoc标签@ apiNote，@ implSpec和@implNote
cunhui1209的博客
12-18 4392
@apinote 如果您已经在使用Java 8，则可能会看到一些新的Javadoc标签： @apiNote ， @implSpec和@implNote 。 他们怎么了？ 如果要使用它们，该怎么办？ 总览 该帖子将快速查看标签的来源和当前状态。 然后，它将解释它们的含义并详细说明如何将它们与IDE，Javadoc工具一起使用，以及如何通过Maven的Javadoc插件使用。 我在GitHub上创...
javadoc 标签_新的Javadoc标签@ apiNote，@ implSpec和@implNote
最佳 Java 编程
06-19 1908
javadoc 标签 如果您已经在使用Java 8，则可能会看到一些新的Javadoc标签： @apiNote ， @implSpec和@implNote 。 他们怎么了？ 如果要使用它们，该怎么办？ 总览 该帖子将快速查看标签的来源和当前状态。 然后，它将解释它们的含义并详细说明如何将它们与IDE，Javadoc工具一起使用，以及如何通过Maven的Javadoc插件使用。 我在Gi...
Java API学习笔记（一）
勿忘初心
07-31 4084
1. 不要重复初始化变量默认情况下，调用类的构造函数时，java会把变量初始化成确定的值，所有的对象被设置成null，整数变量设置成0，float和double变量设置成0.0，逻辑值设置成false。当一个类从另一个类派生时，这一点尤其应该注意，因为用new关键字创建一个对象时，构造函数链中的所有构造函数都会被自动调用。这里有个注意，给成员变量设置初始值但需要调用其他方法的时候，最好放在一个方法
Eclipse下添加java API注释
Stay Hungry, Stay Foolish
11-12 1693
如果你想查看JDK自带的源代码，可以选择JAVA_HOME目录下的src.zip文件进行查看。 没有找到src.zip文件，说明你安装的JDK没有共享源代码，可以到oracle官网下载安装新的JDK。 如果你使用的是Eclipse，而且JDK自带源码没有丝毫注释，就会出现如下提示： Note: The attached Javadoc could not be retrieved a
SCA_JAVA通用注解和API规范_读书笔记
02-04
SCA JAVA通用注解和API规范读书笔记
Java 8 新增Javadoc标记(apiNote, implSpec, implNote)详解
Java 8 版本中引入了新的 Javadoc 标记，包括 @apiNote、@implSpec 和 @implNote。这些标签是为了解决原有标记在特定情况下表达不够清晰的问题，以及为了增强文档的可读性和维护性。 - @apiNote 标签：该标签用于...
package com.example.kucun2.entity.data; import android.os.Handler; import android.os.Looper; import android.util.Log; import java.util.ArrayList; import java.util.Collections; import java.util.HashMap; import java.util.List; import java.util.Map; import java.util.concurrent.CopyOnWriteArrayList; import java.util.concurrent.ExecutorService; import java.util.concurrent.Executors; /** 线程安全的异步操作列表 @param 列表元素类型，需继承自 SynchronizableEntity @apiNote 提供异步添加/移除元素功能，支持UI监听器通知 @threadSafe 内部使用 CopyOnWriteArrayList 保证线程安全 */ public class SynchronizedList { private static final String TAG = “SynchronizedList”; // 使用静态线程池提高效率 private static final ExecutorService ASYNC_EXECUTOR = Executors.newFixedThreadPool(4); // 主线程处理器 private final Handler mainHandler = new Handler(Looper.getMainLooper()); // 内部存储（线程安全） private final List internalList = new CopyOnWriteArrayList<>(); // 列表变更监听器 private final List listeners = new ArrayList<>(); private Class type; /** 构造方法 @param type 列表元素类型（用于反射） */ public SynchronizedList(Class type) { this.type = type; } /** 获取列表元素类型 @return 元素类型Class对象 */ public Class getType() { return type; } //================ 监听器接口 ================// /** 列表变更监听器接口 @param 元素类型 / public interface ListChangeListener { /* 元素添加事件 @param item 添加的元素 @param position 添加位置 */ void onItemAdded(T item, int position); /** 元素移除事件 @param item 移除的元素 @param position 移除位置 */ void onItemRemoved(T item, int position); /** 元素更新事件 @param item 更新的元素 @param position 更新位置 */ void onItemUpdated(T item, int position); /** 同步开始事件 @param item 正在同步的元素 */ void onSyncStarted(T item); /** 同步成功事件 @param item 同步成功的元素 */ void onSyncSuccess(T item); /** 同步失败事件 @param item 同步失败的元素 @param error 错误信息 */ void onSyncFailure(T item, String error); /** 列表整体变更事件 */ void onListChanged(); } /** 操作回调接口 @param 元素类型 / public interface OperationCallback { /* 操作成功回调 @param item 操作的元素 */ void onSuccess(T item); /** 操作失败回调 @param item 操作的元素 @param error 错误信息 */ void onFailure(T item, String error); } //================ 监听器管理 ================// /** 添加列表变更监听器 @param listener 要添加的监听器 */ public void addListChangeListener(ListChangeListener listener) { if (listener != null) { listeners.add(listener); } } /** 移除列表变更监听器 @param listener 要移除的监听器 */ public void removeListChangeListener(ListChangeListener listener) { listeners.remove(listener); } /** 通知所有监听器（在主线程执行） @param action 要执行的通知动作 */ private void notifyListeners(Runnable action) { mainHandler.post(() -> { for (ListChangeListener listener : listeners) { action.run(); } }); } //================ 列表合并操作 ================// /** 合并外部列表到当前列表（不触发同步） @param externalList 外部列表集合 @apiNote 根据元素的id属性进行合并： 如果id存在则更新数据 如果id不存在则添加新元素 不会触发任何同步操作 */ public void mergeList(List externalList) { if (externalList == null || externalList.isEmpty()) { return; } // 创建ID映射表用于快速查找 Map<Integer, T> idMap = new HashMap<>(); for (T item : internalList) { idMap.put(item.getId(), item); } // 记录需要通知的变化 List changeNotifications = new ArrayList<>(); for (T externalItem : externalList) { Integer id = externalItem.getId(); if (idMap.containsKey(id)) { // ID存在 - 更新现有元素 T existingItem = idMap.get(id); int position = internalList.indexOf(existingItem); // 更新元素数据（保留原始对象的引用） if (existingItem != null) { existingItem.updateFrom(externalItem); } // 记录更新通知 changeNotifications.add(() -> { for (ListChangeListener listener : listeners) { listener.onItemUpdated(existingItem, position); } }); } else { // ID不存在 - 添加新元素 int position = internalList.size(); internalList.add(externalItem); // 记录添加通知 changeNotifications.add(() -> { for (ListChangeListener listener : listeners) { listener.onItemAdded(externalItem, position); } }); // 添加到ID映射表 idMap.put(id, externalItem); } } // 批量通知变化 if (!changeNotifications.isEmpty()) { notifyListeners(() -> { for (Runnable notification : changeNotifications) { notification.run(); } // 最后通知列表整体变化 for (ListChangeListener listener : listeners) { listener.onListChanged(); } }); } } /** 异步合并外部列表到当前列表 @param externalList 外部列表集合 @apiNote 在后台线程执行合并操作，完成后在主线程通知UI */ public void mergeListAsync(List externalList) { ASYNC_EXECUTOR.execute(() -> mergeList(externalList)); } //================ 异步操作 ================// /** 异步添加元素 @param item 要添加的元素 @param callback 操作结果回调 @implNote 1. 立即添加元素到列表（UI可见） 后台执行同步操作 根据同步结果更新状态 */ public void addAsync(T item, OperationCallback callback) { if (item == null || internalList.contains(item)) return; // 1. 预添加状态（UI可立即显示） int position = internalList.size(); internalList.add(item); // 通知UI元素添加和同步开始 notifyListeners(() -> { for (ListChangeListener listener : listeners) { listener.onItemAdded(item, position); listener.onSyncStarted(item); } }); // 2. 后台执行同步 ASYNC_EXECUTOR.execute(() -> { // 使用"create"操作类型进行同步 item.sync(“add”, new SynchronizableEntity.SyncCallback() { @Override public void onSyncSuccess(SynchronizableEntity entity) { // 同步成功，通知监听器 notifyListeners(() -> { for (ListChangeListener listener : listeners) { listener.onSyncSuccess((T) entity); listener.onListChanged(); } }); // 执行成功回调 if (callback != null) callback.onSuccess((T) entity); } @Override public void onSyncFailure(String error) { // 同步失败，回滚列表 internalList.remove(item); // 通知UI元素移除和同步失败 notifyListeners(() -> { for (ListChangeListener listener : listeners) { listener.onSyncFailure((T) item, error); listener.onItemRemoved((T) item, position); } }); // 执行失败回调 if (callback != null) callback.onFailure((T) item, error); } }); }); } /** 异步移除元素 @param item 要移除的元素 @param callback 操作结果回调 @implNote 1. 立即从列表移除元素（UI可见） 后台执行同步操作 根据同步结果决定是否回滚 */ public void removeAsync(T item, OperationCallback callback) { if (!internalList.contains(item)) return; // 记录位置用于可能的回滚 int position = internalList.indexOf(item); internalList.remove(item); // 通知UI元素移除和同步开始 notifyListeners(() -> { for (ListChangeListener listener : listeners) { listener.onItemRemoved(item, position); listener.onSyncStarted(item); } }); // 后台执行同步 ASYNC_EXECUTOR.execute(() -> { // 使用"delete"操作类型进行同步 item.sync(“delete”, new SynchronizableEntity.SyncCallback() { @Override public void onSyncSuccess(SynchronizableEntity entity) { // 同步成功，通知监听器 notifyListeners(() -> { for (ListChangeListener listener : listeners) { listener.onSyncSuccess((T) entity); } }); // 执行成功回调 if (callback != null) callback.onSuccess((T) entity); } @Override public void onSyncFailure(String error) { // 同步失败，回滚列表 internalList.add(position, item); // 通知UI元素添加回和同步失败 notifyListeners(() -> { for (ListChangeListener listener : listeners) { listener.onSyncFailure((T) item, error); listener.onItemAdded(item, position); } }); // 执行失败回调 if (callback != null) callback.onFailure((T) item, error); } }); }); } //================ 列表访问 ================// /** 获取不可修改的列表视图 @return 不可修改的列表视图 @apiNote 用于RecyclerView等UI组件 */ public List getViewList() { return Collections.unmodifiableList(internalList); } /** 获取列表大小 @return 列表元素数量 */ public int size() { return internalList.size(); } /** 获取指定位置的元素 @param index 元素位置 @return 指定位置的元素 @throws IndexOutOfBoundsException 如果索引越界 */ public T get(int index) { return internalList.get(index); } } 确保进入集合的实体类的 state属性都为1（已加入集合，关联实体不用懒加载），新建为0（未加入集合，关联实体要在集合中查找并关联），外界的所有同步都是经过该集合，这个state是为了区分依赖的，一个实体类被api加载和新建时关联对象都没有确定关系，只有在该集合中的 数据才算，其他不用管
最新发布
06-29
修改1：添加findById方法修改2：在mergeList方法中添加对新元素调用onAddedToList，对更新元素调用updateAssociations修改3：在addAsync和removeAsync方法中添加对onAddedToList和onRemovedFromList的调用由于代码较...
JavaDoc 生成自己的api文档
super_mokey21的博客
01-03 147
JavaDoc 生成自己的api文档 pojo POJO（Plain Ordinary Java Object）简单的Java对象，实际就是普通JavaBeans，是为了避免和EJB混淆所创造的简称。 package com.monkey.pojo; /** * @author Monkey 作者 * @version 1.0 版本 * @since 1.8 */ public class Doc { String name; /** * * @p
demo-javadoc-8-tags:演示 Java 8 中使用的新 Javadoc 标记
07-02
Javadoc 8 标签 该项目为提供了关于新的 Javadoc 标签@apiNote 、 @implSpec和@implNote的代码示例，这些标签首先在 Java 8 中使用。 这包括： 使用它们的接口 显示如何继承标签的类： 没有实现默认方法~> 该方法在类注释中没有文档块 没有为其实现提供 Javadoc ~> 默认方法的文档被复制（并添加了注释）而没有新标签 使用{@inheritDoc} ~> 继承没有新标签的文档 使用，例如， @apiNote {@inheritDoc} ~> 继承那些特定的标签 需要让 Maven 参数化 Javadoc 以便它处理标签 使 Maven 厌恶者的事情变得更容易一些
javadoc自定义的
07-06
javadoc自定义的
token验证的方法
jcc4261的博客
11-12 1385
NoAuthorization.java 在 TokenInterceptor 将获取到的user数据信息添加到 本地线程UserThreadLocal中去 TokenInterceptor类中实现了HandlerInterceptor拦截器，对请求进行了拦截 并对token进行了校验，token有效就会把user数据信息存储到UserThreadLocal当前类中 通过调用该类的get()方法时，即可获取到user的数据信息UserThreadLocal.java TokenInter
VSCode中的注释标签
m0_61629312的博客
12-30 824
@apiNote: 提供有关API使用的注释或说明。 @author: 标识代码作者的信息。 @category: 可能用于标记代码或功能所属的类别或分类。 @deprecated: 用于标记已经过时或不推荐使用的代码、方法或类。 @implNote: 提供有关代码实现的注释或说明。 @implSpec: 给出关于代码实现规范的注释。 @see: 用于指向其他相关资源、类、方法等的参考链接。 @serial: 通常用于序列化对象时指定版本。 @since: 指定代码、方法或类添加到代码库中的版本。
【Smart-Doc】 使用说明
Forget_G的博客
12-01 4805
smart-doc 使用介绍 基于2.6.2版本
【JavaDoc】都什么年代了，还在写传统注释（Java新建类自动加注释）
m0_52142443的博客
11-02 211
在网上查了一些自动加注释，基本都是要加上自定义标签，这样的话会让idea识别不出来，每次都需要添加自定义标签，而且idea没法在阅读器模式中识别这些标签，那么使用Javadoc的标签显然会更好。
NVMe控制器寄存器
百里杨的博客
01-03 3349
NVMe控制器寄存器，位于配置空间BAR0与BAR1，所映射的内存空间中。BAR0为低32位，BAR1为高32位，一起组合为64位内存地址，表示PCIe设备内存空间的基址。NVMe控制器寄存器，就位于该内存空间中，并且host访问这些寄存器，应按原始宽度或32位对齐来访问。由于NVMe控制器寄存器，位于PCIe设备内存空间中，因此上表中Start和End列，是相对于PCIe设备内存空间基址的偏移。
JDK8中Map接口的源码分析
iCoding91
11-11 1037
package sourcecode.analysis; /** * Created by caoxiaohong on 17/11/11 11:44. * Map接口分析 */ import java.io.Serializable; import java.lang.*; import java.util.*; import java.util.function.*; import ...
Javadoc标签
戎码人生
09-12 1396
javadoc 标签 javadoc工具软件识别以下标签： 标签 描述 示例 @author 标识一个类的作者 @author description @deprecated 指名一个过期的类或成员 @deprecated description {@docRoot} 指明当前文档根目录的路径 Directory Path @exception 标
spec中内容格式
fan475773556的专栏
01-04 1413
.spec文件的格式及其中间的内容是 Name:           lsyncd Version:        2.0.5 Release:        1%{?dist} Summary:        lsyncd is a soft of data sync. Group:          System Environmen/Base License:      
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值