在 Dart 中使用 setter 和 getter 记录变量的约定是什么？

Question

考虑以下示例（如果您使用提供者 Flutter 包则很常见）：您有一个 class 和一个可以通过 setter 和 getter 访问的私有变量.对此进行记录的惯例/推荐方式是什么？

class Foo extends ChangeNotifier {

  int _bar = 0;

  int get bar => bar;

  set bar(int bar){
    _bar = bar;
    notifyListeners();
  }
}

你应该在 setter 和 getter 中添加文档注释并在两个注释中解释变量的用途，还是应该只在私有变量中添加文档注释？

例如：

class Foo extends ChangeNotifier {

  /// The number of bars in the foo.
  int _bar = 0;

  /// Get the number of bars in the foo.
  int get bar => bar;

  /// Set the number of bars in the foo.
  set bar(int bar){
    _bar = bar;
    notifyListeners();
  }
}

对比

class Foo extends ChangeNotifier {

  /// The number of bars in the foo.
  int _bar = 0;

  int get bar => _bar;

  set bar(int bar){
    _bar = bar;
    notifyListeners();
  }
}

第一个例子是最清楚的，但它可能意味着很多重复的评论。第二个示例减少了评论的数量，但要查看 getter / setter 的作用并不容易（例如通过在 vs 代码中将鼠标悬停在它上面）。 Dart 团队是否有关于在这种情况下应如何编写文档的建议或约定？

Answer 1

文件，传统上是 getter。像记录字段一样使用名词短语记录它。然后 DartDoc 工具会将其显示为一个字段。 https://dart.dev/guides/language/effective-dart/documentation#prefer-starting-variable-getter-or-setter-comments-with-noun-phrases

在 Dart 中使用 setter 和 getter 记录变量的约定是什么？

What is the convention for documenting variables with setters and getters in Dart?

code-documentation

dart