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 자 이상이고 필수 요소 (개요·상세·마커)를 포함

1. 기존 코멘트가 기준을 만족하지 않는 경우: 완전히 교체 (중복시키지 않음)
2. 기존 코멘트가 없는 경우: 새로운 코멘트를 추가

보존해야 할 중요 정보:

• 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
• 추가·업데이트한 코멘트가 모두 기준을 만족

1. 부분 성공: 다음의 경우

• 에러 발생 수가 5 건 미만
• 전체의 90% 이상이 기준을 만족

1. 실패: 다음의 경우

• melos analyze가 FAILED
• 에러 발생 수가 5 건 이상