CODEWITHSUNDEEP
dartcode-documentation
Hannes Hultergård
Hannes Hultergård

Reputation: 1217

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

Consider the following example (common if you use the provider Flutter package): You have a class with a private variable that can be accessed via a setter and a getter. What is the convention / recommended way to document this?

class Foo extends ChangeNotifier {

  int _bar = 0;

  int get bar => bar;

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

Should you add doc comments to both the setter and getter and explain the purpose of the variable in both comments, or should you just add a doc comment to the private variable?

For example:

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();
  }
}

vs.

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();
  }
}

The first example is the most clear one, but it can possibly mean a lot of duplicate comments. The second example reduces the amount of comments, but it isn't as easy to see what the getter / setter does (for example by hovering over it in vs code). Is there a recomendatin by the Dart team or a convention for how documentation should be written in cases like this?

Upvotes: 0

Views: 410

Answers (1)

lrn
lrn

Reputation: 71773

Document either, traditionally the getter. Document it as you would a field, using a noun phrase. The DartDoc tool will then show it as a field. https://dart.dev/guides/language/effective-dart/documentation#prefer-starting-variable-getter-or-setter-comments-with-noun-phrases

Upvotes: 3

Related Questions