라이브러리 문서 주석은 library 지시문에 붙여 주세요

///로 작성한 라이브러리 문서 주석은 파일 위쪽에 그냥 두지 말고 library; 지시문에 붙여 주는 게 좋아요. 그래야 문서화 도구가 라이브러리에 대한 설명으로 제대로 인식해요.

출처: Attach library doc comments to library directives

본문

라이브러리 문서 주석(///)은 library 지시문에 붙여 주세요.

라이브러리 위쪽에 그냥 떠 있게("dangling") 두지 말고 library 지시문에 붙여 주세요.

BAD:

/// This is a great library.
import 'package:math';

BAD:

/// This is a great library.

class C {}

GOOD:

/// This is a great library.
library;

import 'package:math';

class C {}

참고: 위 library;처럼 이름 없는 라이브러리는 Dart 2.19 이상에서만 지원돼요. 더 이른 버전의 Dart에서 실행될 수 있는 코드라면 library 지시문에 이름을 제공해야 해요.

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

linter:
  rules:
    - dangling_library_doc_comments

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

linter:
  rules:
    dangling_library_doc_comments: true