Dart 주석 - Dart 튜토리얼

Dart 언어는 주석을 총 3가지 지원합니다：한 줄 주석, 여러 줄 주석, 문서 주석；컴파일러는 일반 주석 텍스트를 무시하며 문서 주석만 코드 문서 생성에 사용할 수 있습니다.

주석의 목적은 개발자가 코드의 기능과 역할을 쉽게 파악할 수 있도록 돕는 것입니다. 또한 임시로 코드를 비활성화하여 디버깅 및 문제점 탐색에 활용할 수도 있습니다.

문서 주석은 전용 도구로 코드 API 도움말 문서를 자동 생성할 수 있습니다. 본인이 작성한 코드 스펙 확인은 물론 다른 사람이 라이브러리를 사용할 때 참고 자료로 활용됩니다.

C/C++/Java/C# 등 C 계열 언어를 공부했다면 매우 빠르게 이해할 수 있습니다. 문법이 거의 동일합니다.

1、한 줄 주석 //

//로 시작；
//부터 줄 끝까지 모든 내용은 Dart 컴파일러가 무시；
현재 줄에만 적용되며 여러 줄에 걸쳐 사용할 수 없음.

예시

void main() {
  // TODO: 라마 인사 공장 추상 클래스로 리팩토링?
  print('라마 농장에 오신 것을 환영합니다!');
}
Code language: JavaScript (javascript)

2、여러 줄 주석 /* */

시작 표시 /*, 종료 표시 */；
/* 와 */ 사이 모든 내용은 컴파일러가 무시（아래 문서 주석 제외）；
중첩 작성 지원.

예시

void main() {
  /*
   * 라마 키우는 일이 힘들어 닭을 키우는 것을 고려해볼 수 있다

  Llama larry = Llama();
  larry.feed();
  larry.exercise();
  larry.clean();
   */
}

위 코드에서 중괄호 안의 모든 코드는 주석 처리되어 컴파일되지 않으며 컴파일러가 해당 부분을 무시합니다.

3、문서 주석

공식 API 문서 생성에 사용하며 다른 개발자가 라이브러리를 사용할 때 클래스, 함수 인터페이스, 매개변수 등 사용 설명서로 참고할 수 있습니다.

1. 두 가지 작성 형식

한 줄 문서 주석: 여러 줄에 걸쳐 /// 사용, 여러 줄 문서 주석과 동일한 효과. 슬래시가 세 개라는 점 유의.
여러 줄 문서 주석: /**로 시작, */로 종료. 시작 부분에 별표 하나가 추가된 점 유의.

2. 핵심 문법 규칙

문서 주석 내 일반 텍스트는 코드 분석기가 무시；
대괄호 []로 식별자를 감싸는 특수 문법: 클래스, 메서드, 필드, 최상위 변수, 함수, 매개변수를 참조 가능；
대괄호 안 이름은 주석 대상 코드의 어휘 범위 내에서 해석；
문서 생성 후 [식별자]는 해당 문서로 이동하는 하이퍼링크로 자동 변환.

예시

// 일반 한 줄 주석: 사료 클래스 정의
class Food {
  String type;
  // 한 줄 주석: 사료 묶음 수
  int baleCount;

  Food(this.type, this.baleCount);
}

/*
일반 여러 줄 주석:
운동 타입 열거형, 라마 운동 메서드에 사용
중첩 주석 예시
/* 내부 중첩 주석 */
*/
enum Activity {
  walk,
  run,
  graze
}

/// 길들여진 남미 낙타과 동물（라마, 학명Lama glama）
///
/// 콜럼버스 이전 안데스 문명은 라마를 식량과 운송 가축으로 활용했습니다.
///
/// 다른 동물처럼 라마는 먹이가 필요합니다. [Food] 타입 사료를 주고 [feed] 메서드를 호출하세요.
class Llama {
  String? name;

  /// 지정한 [food] 사료를 라마에게 먹이기
  ///
  /// 한 마리 라마는 일주일에 건초 한 묶음을 소비하는 것이 일반적입니다.
  void feed(Food food) {
    // 한 줄 주석: 먹이 로그 출력
    print("${name}이 ${food.baleCount}묶음의 ${food.type}을 먹었습니다");
  }

  /// 라마에게 [activity] 운동을 [timeLimit]분간 시키기
  void exercise(Activity activity, int timeLimit) {
    print("${name}이 ${activity.name} 운동을 ${timeLimit}분간 했습니다");
  }
}

void main() {
  // TODO：추후 여러 마리 라마 관리 기능 확장
  Llama larry = Llama();
  larry.name = "라리";

  // 건초 사료 생성
  Food hay = Food("건초", 1);
  larry.feed(hay);

  // 라마 20분 산책
  larry.exercise(Activity.walk, 20);
}

문서 생성 후：[feed]는 현재 클래스의 feed 메서드 문서로 링크되고, [Food]는 Food 클래스 문서로 링크됩니다.

D:\dartdemo\firstdart>dart run
Building package executable...
Built firstdart:firstdart.
라리가 1묶음의 건초을 먹었습니다
라리가 walk 운동을 20분간 했습니다

D:\dartdemo\firstdart>dart doc
Documenting firstdart...
Discovering libraries...
Linking elements...
Precaching local docs for 136851 elements...
Initialized dartdoc with 50 libraries
Generating docs for library firstdart.dart from package:firstdart/firstdart.dart...
Found 0 warnings and 0 errors.
Documented 1 public library in 10.3 seconds
Success! Docs generated into d:\dartdemo\firstdart\doc\api

실행 후 프로젝트 폴더 안에 doc 폴더가 생성되며 열어보면 아래 문서를 확인할 수 있습니다

연계 도구

문서 생성 도구：dart doc 역할：Dart 소스 코드를 분석해 HTML 형식 프로젝트 API 문서 자동 생성. Dart 공식 API 문서도 이 도구로 만들어집니다.
주석 작성 규범 참고：공식 가이드 《Effective Dart: Documentation》, 표준화된 주석 구조와 스타일 확인 가능.

요약

비교표

주석 종류	시작 기호	여러 줄 지원	중첩 지원	사용 용도
한 줄 주석	`//`	미지원, 현재 줄만	불가	임시 한 줄 메모, 코드 TODO
일반 여러 줄 주석	`/* */`	임의의 여러 줄 지원	중첩 가능	긴 코드 블록 일괄 주석 처리, 긴 설명 작성
문서 주석	`///` / `/** */`	여러 줄 지원	중첩 권장하지 않음	클래스/메서드/변수 API 설명 작성, 공식 문서 생성, `[]`로 식별자 링크 지원

Previous: Dart 전개 연산자

Next: Dart 내장 타입