모든 public 멤버에 문서를 달아주세요

모든 public 멤버에 문서를 달아주세요

public 멤버를 모두 문서화하라는 린트 규칙이에요. 라이브러리를 만드는 사람이라면 꼭 필요한 규칙이죠. 함께 볼게요.

출처: public_member_api_docs

본문

모든 public 멤버를 문서화하세요.

오버라이드(override)되지 않은 모든 public 멤버는 /// 문서 스타일 주석으로 문서화해야 해요.

BAD:

class Bad {
  void meh() { }
}

GOOD:

/// A good thing.
abstract class Good {
  /// Start doing your thing.
  void start() => _start();

  _start();
}

public 멤버가 다른 멤버를 오버라이드하는 경우에는, 문서를 제공할 책임은 선언하는 쪽 멤버에 있어요. 예를 들어 아래 예시에서 Sub는 init을 문서화할 필요가 없어요. 물론 필요하다면 얼마든지 문서화해도 되지만요.

GOOD:

/// Base of all things.
abstract class Base {
  /// Initialize the base.
  void init();
}

/// A sub base.
class Sub extends Base {
  @override
  void init() { ... }
}

dart doc과 일관되게, 문서화된 getter에 대응하는 문서화되지 않은 setter가 있는 경우에는 예외가 적용돼요. 이 경우 setter는 getter의 문서를 상속받아요.

켜는 방법

public_member_api_docs 규칙을 사용하려면 analysis_options.yaml 파일의 linter > rules 아래에 public_member_api_docs를 추가해요:

linter:
  rules:
    - public_member_api_docs

만약 YAML 맵 문법으로 린트 규칙을 설정한다면 linter > rules 아래에 public_member_api_docs: true를 추가하면 돼요:

linter:
  rules:
    public_member_api_docs: true

더 알아보기