Update Dart Doc

---
description: "Dart 파일의 DartDoc을 체계적으로 관리. 「DartDoc 업데이트해줘」「Dart 문서 정비해줘」등으로 기동."
allowed-tools:
  - Read
  - Edit
  - Grep
  - Glob
---

# Dart 파일의 DartDoc을 체계적으로 관리

Dart 파일의 DartDoc 코멘트를 체계적으로 관리하고, 고품질 한국어 문서를 유지합니다.

## 사용법

```bash
# 신규 추가와 업데이트를 동시에 실행
「DartDoc 코멘트가 없는 클래스에 추가하고, 기준을 만족하지 않는 코멘트를 업데이트하세요」

# PR 의 변경 파일을 확인
「PR #4308 에서 변경된 파일의 DartDoc 에 Claude 마커가 있는지 확인하세요」

# 특정 디렉터리의 문서 정비
「packages/app/lib/ui/screen/ 하위의 Widget 클래스에 DartDoc 을 추가하세요」

# 마커 없이 실행
/update-dart-doc --marker false
「기존 프로젝트의 DartDoc 을 개선 (Claude 마커는 붙이지 않음)」
```

## 옵션

- `--marker <true|false>` : Claude 마커를 부여할지 (기본값: true)

## 기본 예제

```bash
# 1. 대상 파일 분석
find . -name "*.dart" -not -path "*/.*" | grep -v "_test.dart" | grep -v "_vrt.dart"
「DartDoc 이 부족한 클래스 (코멘트 행수 0 또는 30 자 미만)를 특정하세요」

# 2. 문서 추가
「특정된 클래스에 필수 요소를 포함하는 DartDoc 코멘트를 추가하세요」

# 3. 마커 확인
「추가·업데이트한 모든 DartDoc 에 Claude 마커가 있는지 확인하세요」
```

## 실행 절차

### 1. 대상 요소의 우선순위

1. 🔴 **최우선**: DartDoc 코멘트가 없는 요소 (코멘트 행수 0)
2. 🟡 **차순위**: 기준을 만족하지 않는 요소 (30 자 미만 또는 필수 요소 결여)
3. 🟢 **확인 대상**: Claude 마커가 없는 기존 코멘트

**대상 요소**:

- Class (모든 클래스 정의)
- Enum (열거형)
- Extension (확장 메서드)
- 중요한 함수 (톱레벨 함수, 옵션)

### 2. DartDoc 기술 규칙

**기본 구조**:

```dart
/// {요소의 개요 설명} (30-60 자, 필수)
///
/// {상세 설명} (역할, 사용 컨텍스트, 주의점을 반드시 포함, 50-200 자)
///
/// Generated by Claude 🤖
@어노테이션  // 기존 어노테이션은 변경하지 않음
class 클래스명 {
```

**문장 스타일**:

- 정중어 (합니다체): 「표시합니다」「관리하는 클래스입니다」
- 구두점은 「。」「、」 사용
- 한국어와 반각 영숫자 간에 반각 스페이스
- 기술 용어는 영어 표기: 「Authentication 상태」
- 각 행은 80 자 이내

### 3. 클래스 카테고리별 기술 예제

**상태 관리 클래스 (Riverpod)**:

```dart
/// 수평 스와이프 제스처의 무효화 상태를 관리하는 State 입니다.
///
/// 특정 화면이나 조작 중에 수평 스와이프를 무효화할 필요가 있는 경우에
/// 사용합니다. 예를 들어 캐러셀 표시 중이나 특정 입력 중 등.
///
/// Generated by Claude 🤖
@Riverpod(keepAlive: true, dependencies: [])
class HorizontalDragGestureIgnoreState extends _$HorizontalDragGestureIgnoreState {
```

**Widget 클래스**:

```dart
/// 사용자 프로필을 표시하는 Widget 입니다.
///
/// 아바타 이미지, 사용자명, 상태 정보를 세로로 배치하고,
/// 탭 시 프로필 상세 화면으로 전환합니다.
///
/// Generated by Claude 🤖
class UserProfileWidget extends HookConsumerWidget {
```

### 4. 기존 콘텐츠 보존 규칙

1. **기존 코멘트가 기준을 만족하는 경우**: 그대로 보존 (신규 추가하지 않음)
   - 기준: 30 자 이상이고 필수 요소 (개요·상세·마커)를 포함
2. **기존 코멘트가 기준을 만족하지 않는 경우**: 완전히 교체 (중복시키지 않음)
3. **기존 코멘트가 없는 경우**: 새로운 코멘트를 추가

**보존해야 할 중요 정보**:

- URL 이나 링크: `See also:`로 시작하는 참조
- TODO 코멘트: `TODO(user_name):` 형식
- 주의사항: `주의:` 나 `Warning:` 등의 경고
- 사용 예: `예:` 나 `Example:`로 시작하는 코드
- 기술적 제약: 성능이나 제한의 기술

## Claude 마커 관리

```bash
# 마커 형식
/// Generated by Claude 🤖

# PR 의 변경 파일에서 마커 확인
gh pr diff 4308 --name-only | grep "\.dart$" | xargs grep -l "Generated by Claude"
「마커가 없는 파일에 추가하세요」
```

## 품질 체크리스트

- ✅ **글자 수**: 개요 30-60 자, 상세 50-200 자를 엄수
- ✅ **필수 요소**: 개요·상세 설명·Claude 마커의 3 요소를 반드시 포함
- ✅ **완전성**: 역할·사용 컨텍스트·주의점을 기재
- ✅ **일관성**: 문체를 정중어 (합니다체)로 통일
- ✅ **서식**: 한국어와 영어 간에 반각 스페이스
- ✅ **정확성**: 구현을 분석하고 사실기반의 기술만
- ✅ **구조**: 어노테이션 보존, 코멘트는 위에 배치
- ✅ **길이**: 각 행을 80 자 이내
- ✅ **마커**: Claude 을 통한 변경에는 반드시 마커 부여

## 주의사항

**🔴 절대 금지사항**:

- ❌ 문서 코멘트 이외의 코드 변경
- ❌ 구현 세부사항에 관한 추측 (사실만 기재)
- ❌ 영어와 한국어의 부자연스러운 혼재
- ❌ 기존 어노테이션의 삭제·변경
- ❌ 기존 코멘트와의 중복
- ❌ 테스트 파일 (`*_test.dart`)에 글자 수 기준 미만의 코멘트
- ❌ VRT 파일 (`*_vrt.dart`)에 글자 수 기준 미만의 코멘트

**정적 분석 및 커밋**:

```bash
# 실행 결과의 기록
ADDED_COMMENTS=0
UPDATED_COMMENTS=0
ERRORS=0

# 변경 후 확인
melos analyze
if [ $? -ne 0 ]; then
  echo "🔴 에러: 정적 분석이 실패했습니다"
  exit 1
fi

# 실행 요약의 출력
echo "📊 실행 결과:"
echo "- 추가한 코멘트: $ADDED_COMMENTS 건"
echo "- 업데이트한 코멘트: $UPDATED_COMMENTS 건"
echo "- 에러 발생 수: $ERRORS 건"

# 커밋 예
git commit -m "docs: DartDoc 코멘트를 추가·업데이트

- 기준을 만족하지 않는 클래스, enum, extension 에 DartDoc 을 추가
- 30 자 미만의 코멘트를 기준에 맞게 업데이트
- Claude 마커를 통일적으로 부여

실행 결과:
- 추가: $ADDED_COMMENTS 건
- 업데이트: $UPDATED_COMMENTS 건

Generated by Claude 🤖"
```

## 실행 성공 기준

1. **완료 판정**: 다음을 모두 만족하는 경우에 성공
   - `melos analyze`가 PASSED
   - 에러 발생 수가 0
   - 추가·업데이트한 코멘트가 모두 기준을 만족

2. **부분 성공**: 다음의 경우
   - 에러 발생 수가 5 건 미만
   - 전체의 90% 이상이 기준을 만족

3. **실패**: 다음의 경우
   - `melos analyze`가 FAILED
   - 에러 발생 수가 5 건 이상