「API 工具」提供了已新增至 API 的新元素(類型、方法、欄位等等)上之 @since Javadoc 標籤的管理支援。
新的 API 元素可以是新增至 API 套件的新類型、新增至 API 類型的新類型、新增至 API 類型的新方法,或是新增至 API 類型的新欄位。
新增方法是個特殊的情況,因為新增方法可以新增方法至類型、置換母類別方法、實作母項介面方法,或是變更現有方法的簽章。
附註:@since 標籤資訊不會透過實作或建立子類別來傳送。新增至 API 的每一個元素都預期有自己的 @since 標籤和版本資訊。
該工具對 @since 標籤提供了下列驗證:
您可以在
外掛程式開發 > API 錯誤/警告喜好設定頁面變更 @since 標籤管理的喜好設定。
工具會檢查每一個偵測到的新的 API 元素,以確保其有 @since 標籤。
如果新的元素沒有 @since 標籤,其會標示為需要標籤,且會提出該標籤的版本。
對新標籤所提出的版本會是軟體組的現行版本 - 但是岔斷 API 變更的狀況除外,此情況也需要更新軟體組版本。如果也需要更新軟體組版本,針對遺漏 @since 標籤所提出的版本會是已提出的軟體組版本。
請參考以下範例:有一個軟體組 A 的版本為 1.0.0,有一個類別 C 已新增至 1.1.0 版且含有 m1() 方法的 A。
@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