Javadoc @since 标记管理

API 工具支持管理已添加至 API 的新元素(类型、方法和字段等等)的 @since Javadoc 标记。 新的 API 元素可以是已添加至 API 包的新类型、已添加至 API 类型的新类型、新方法或者新字段。 添加方法是一种特殊情况,添加方法可以是将方法添加至某个类型、覆盖父类方法、实现父接口方法或者更改现有方法的特征符。

注意:@since 标记信息不是通过实现或划分子类来传播的。期望添加至 API 的每个元素都具有它自己的 @since 标记和版本信息。

工具对 @since 标记提供了下列验证:

可以在 打开“控制台”首选项页 插件开发 > API 错误/警告首选项页上更改用于 @since 标记管理的首选项。

缺少 @since 标记

工具将检查所检测到的每个新 API 元素,以确保该元素具有 @since 标记。 如果该新元素没有 @since 标记,那么会将它标记为需要一个 @since 标记,并且将建议此标记的版本。 为新标记建议的版本将是捆绑软件的当前版本 - 但是在破坏了 API 更改的情况下除外,这种情况下还需要更新捆绑软件的版本。如果还需要更新捆绑软件版本,那么为缺少的 @since 标记建议的版本将是建议的捆绑软件版本。

请考虑以下示例:假定有一个版本为 1.0.0 的捆绑软件 A,并且在包含方法 m1() 的 A 的版本 1.1.0 中添加了类 C。

@since 标记的格式不正确

新元素可以检查它们的 @since 标记的一致性,以确保正确阐明了这些标记。API 工具将检查是否所有 @since 标记都遵循如下所示的常规格式:

[@since] [pre-amble] [2 part version] [post-amble]

请考虑以下 @since 标记示例:

@since 标记的版本无效

新元素还可以检查它们的 @since 标记的有效性。如果 @since 标记中的版本信息与捆绑软件的版本相匹配,那么认为此标记有效。

请考虑以下示例,我们已将一个新方法 m2() 添加至捆绑软件 A(版本为 1.0.0)中的 API 类:

相关任务
设置基线

相关参考
API 基线首选项
API 错误和警告首选项