주석 문서에는 스코프 안에 있는 식별자만 참조하세요

문서 주석(doc comment)에서 대괄호 [...]로 감싼 식별자는 IDE나 dart doc 같은 도구가 실제 선언으로 링크를 걸 수 있어요. 다만 그렇게 링크를 걸려면 대괄호로 감싼 모든 식별자가 해당 주석이 있는 스코프 안에 존재해야 해요. 이 린트 규칙은 그 규칙을 지키도록 도와줘요.

출처: Only reference in-scope identifiers in doc comments

본문

주석 문서에는 스코프 안에 있는 식별자만 참조하세요.

변수, 메서드, 타입 이름 같은 식별자를 대괄호로 감싸면 IDE와 dart doc 같은 도구가 그것들을 링크로 만들어 줘요. 이게 제대로 동작하려면 대괄호로 감싼 모든 식별자가 스코프 안에 있어야 해요.

예를 들어 outOfScopeId가 스코프 밖에 있다고 가정해 볼게요.

BAD:

/// Returns whether [value] is larger than [outOfScopeId].
bool isOutOfRange(int value) { ... }

GOOD:

/// Returns the larger of [a] or [b].
int max_int(int a, int b) { ... }

대괄호 주석 형식은 주석이 비교적 자연스러운 형태로 선언을 참조하도록 설계되었지만, 임의의 표현식은 허용하지 않아요. 특히 대괄호 안의 코드 참조는 다음 중 하나로 구성될 수 있어요.

주석에 대해 스코프 안에 있는 단순 식별자(문서 주석에서 "스코프 안"이 무엇을 뜻하는지는 명세를 참고하세요). 예로 [print], [Future]가 있어요.
마침표로 구분된 두 개의 식별자("프리픽스 식별자") — 첫 번째 식별자는 네임스페이스 역할을 해요. 예를 들어 클래스의 프로퍼티 이름이나 클래스 이름으로 프리픽스를 붙인 메서드 이름, import 프리픽스로 프리픽스를 붙인 최상위 식별자 등이 해당돼요. 예로 [Future.new](이름 없는 생성자), [Future.value](생성자), [Future.wait](정적 메서드), [Future.then](인스턴스 메서드), [math.max](dart:async를 max 프리픽스로 import했다고 가정)가 있어요.
이름이 충돌할 수 있는 생성자와 인스턴스 멤버를 구분하기 위해 괄호 쌍이 붙은 프리픽스 식별자. 예로 [Future.value()]가 있어요.
마침표 두 개로 구분된 세 개의 식별자 — 첫 번째 식별자는 import 프리픽스 이름, 두 번째 식별자는 클래스나 extension 같은 최상위 요소, 세 번째 식별자는 그 최상위 요소의 멤버예요. 예로 [async.Future.then](dart:async를 async 프리픽스로 import했다고 가정)가 있어요.

알려진 제한 사항

comment_references 린트 규칙은 Dart 분석기의 주석 참조 개념과 일치하는데, 이는 때때로 Dartdoc의 주석 참조 개념과는 다를 수 있어요. 이 린트 규칙은 분석기가 해결할 수 없더라도 Dartdoc이 해결할 수 있는 주석 참조를 보고할 수 있어요. 자세한 내용은 sdk#57783을 참고하세요.

활성화 방법

comment_references 규칙을 활성화하려면 analysis_options.yaml 파일의 linter > rules 아래에 comment_references를 추가하면 돼요.

linter:
  rules:
    - comment_references

대신 YAML map 문법으로 린트 규칙을 설정한다면 linter > rules 아래에 comment_references: true를 추가하면 돼요.

linter:
  rules:
    comment_references: true

주석 문서에는 스코프 안에 있는 식별자만 참조하세요