API 工具支持管理已添加至 API 的新元素(类型、方法和字段等等)的 @since Javadoc 标记。
新的 API 元素可以是已添加至 API 包的新类型、已添加至 API 类型的新类型、新方法或者新字段。
添加方法是一种特殊情况,添加方法可以是将方法添加至某个类型、覆盖父类方法、实现父接口方法或者更改现有方法的特征符。
注意:@since 标记信息不是通过实现或划分子类来传播的。期望添加至 API 的每个元素都具有它自己的 @since 标记和版本信息。
工具对 @since 标记提供了下列验证:
可以在
插件开发 > API 错误/警告首选项页上更改用于 @since 标记管理的首选项。
工具将检查所检测到的每个新 API 元素,以确保该元素具有 @since 标记。
如果该新元素没有 @since 标记,那么会将它标记为需要一个 @since 标记,并且将建议此标记的版本。
为新标记建议的版本将是捆绑软件的当前版本 - 但是在破坏了 API 更改的情况下除外,这种情况下还需要更新捆绑软件的版本。如果还需要更新捆绑软件版本,那么为缺少的 @since 标记建议的版本将是建议的捆绑软件版本。
请考虑以下示例:假定有一个版本为 1.0.0 的捆绑软件 A,并且在包含方法 m1() 的 A 的版本 1.1.0 中添加了类 C。
@since 标记”问题,并且会建议对 m2() 添加新标记 @since 1.1。@since 标记”问题,并且会建议对 m2() 添加新标记 @since 2.0。其中 2.0.0 是建议的新捆绑软件版本。
新元素可以检查它们的 @since 标记的一致性,以确保正确阐明了这些标记。API 工具将检查是否所有 @since 标记都遵循如下所示的常规格式:
[@since] [pre-amble] [2 part version] [post-amble]
请考虑以下 @since 标记示例:
@since A 1 added m2():将被标记为格式不正确,这是因为此版本缺少第二个段@since:将被标记为格式不正确,这是因为没有版本信息@since A:将被标记,这是因为没有版本信息@since 1.0.0:将被标记,这是因为此版本具有太多段@since A 1.0 added m2():将不会被标记
新元素还可以检查它们的 @since 标记的有效性。如果 @since 标记中的版本信息与捆绑软件的版本相匹配,那么认为此标记有效。
请考虑以下示例,我们已将一个新方法 m2() 添加至捆绑软件 A(版本为 1.0.0)中的 API 类:
@since A 1.0 added method m2():被认为有效@since A 2.0 added method m2():这是无效的,因为捆绑软件 A 的版本为 1.0.0@since A 0.1 added method m2():这是无效的,因为捆绑软件 A 的版本为 1.0.0