Javadoc @since 標籤管理

「API 工具」提供了已新增至 API 的新元素(類型、方法、欄位等等)上之 @since Javadoc 標籤的管理支援。 新的 API 元素可以是新增至 API 套件的新類型、新增至 API 類型的新類型、新增至 API 類型的新方法,或是新增至 API 類型的新欄位。 新增方法是個特殊的情況,因為新增方法可以新增方法至類型、置換母類別方法、實作母項介面方法,或是變更現有方法的簽章。

附註:@since 標籤資訊不會透過實作或建立子類別來傳送。新增至 API 的每一個元素都預期有自己的 @since 標籤和版本資訊。

該工具對 @since 標籤提供了下列驗證:

您可以在 開啟「主控台」喜好設定頁面 外掛程式開發 > API 錯誤/警告喜好設定頁面變更 @since 標籤管理的喜好設定。

遺漏 @since 標籤

工具會檢查每一個偵測到的新的 API 元素,以確保其有 @since 標籤。 如果新的元素沒有 @since 標籤,其會標示為需要標籤,且會提出該標籤的版本。 對新標籤所提出的版本會是軟體組的現行版本 - 但是岔斷 API 變更的狀況除外,此情況也需要更新軟體組版本。如果也需要更新軟體組版本,針對遺漏 @since 標籤所提出的版本會是已提出的軟體組版本。

請參考以下範例:有一個軟體組 A 的版本為 1.0.0,有一個類別 C 已新增至 1.1.0 版且含有 m1() 方法的 A。

@since 標籤形態異常

新的元素可以檢查其 @since 標籤的一致性,以確保其格式適當。API 工具會檢查所有 @since 標籤是否都遵循以下一般格式:

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

請參考下列 @since 標籤範例:

@since 標籤版本無效

新的元素也可以檢查其 @since 標籤的有效性。如果標籤中的版本資訊符合軟體組的版本,則 @since 標籤即視為有效。

請參考下列範例,其中新增了方法 m2() 至軟體組 A(其版本為 1.0.0)的 API 類別中:

相關作業
設定基準線

相關參照
API 基準線喜好設定
「API 錯誤和警告」喜好設定