type_annotate_public_apis

為公共 API 新增型別註解。

摘自 Effective Dart

建議 為公共 API 新增型別註解。

型別註解是關於如何使用庫的重要文件。為公共方法和函式的引數和返回值型別添加註解有助於使用者理解 API 的期望和提供的內容。

請注意，如果公共 API 接受 Dart 型別系統無法表達的一系列值，則可以接受不為其指定型別。在這種情況下，隱式的 dynamic 是該 API 正確的型別。

對於庫內部的程式碼（無論是私有的，還是巢狀函式之類的），請在你認為有幫助的地方添加註解，但不要覺得你必須提供它們。

錯誤示例

install(id, destination) {
  // ...
}

這裡不清楚 id 是什麼。是字串嗎？destination 又是什麼？是字串還是 File 物件？這個方法是同步的還是非同步的？

正確示例

Future<bool> install(PackageId id, String destination) {
  // ...
}

有了型別，所有這些都變得清晰了。

type_annotate_public_apis 規則與以下規則不相容：

• omit_obvious_property_types

要啟用 type_annotate_public_apis 規則，請在你的 analysis_options.yaml 檔案中的 linter > rules 下新增 type_annotate_public_apis

linter:
  rules:
    - type_annotate_public_apis

如果你使用的是 YAML map 語法來配置 linter 規則，請在 linter > rules 下新增 type_annotate_public_apis: true

linter:
  rules:
    type_annotate_public_apis: true