wasabeef Dart 파일의 DartDoc을 체계적으로 관리
Dart 파일의 DartDoc 코멘트를 체계적으로 관리하고, 고품질 한국어 문서를 유지합니다.
사용법
# 신규 추가와 업데이트를 동시에 실행
「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)
기본 예제
# 1. 대상 파일 분석
find . -name "*.dart" -not -path "*/.*" | grep -v "_test.dart" | grep -v "_vrt.dart"
「DartDoc 이 부족한 클래스 (코멘트 행수 0 또는 30 자 미만)를 특정하세요」
# 2. 문서 추가
「특정된 클래스에 필수 요소를 포함하는 DartDoc 코멘트를 추가하세요」
# 3. 마커 확인
「추가·업데이트한 모든 DartDoc 에 Claude 마커가 있는지 확인하세요」
실행 절차
1. 대상 요소의 우선순위
- 🔴 최우선: DartDoc 코멘트가 없는 요소 (코멘트 행수 0)
- 🟡 차순위: 기준을 만족하지 않는 요소 (30 자 미만 또는 필수 요소 결여)
- 🟢 확인 대상: Claude 마커가 없는 기존 코멘트
대상 요소:
- Class (모든 클래스 정의)
- Enum (열거형)
- Extension (확장 메서드)
- 중요한 함수 (톱레벨 함수, 옵션)
2. DartDoc 기술 규칙
기본 구조:
/// {요소의 개요 설명} (30-60 자, 필수)
///
/// {상세 설명} (역할, 사용 컨텍스트, 주의점을 반드시 포함, 50-200 자)
///
/// Generated by Claude 🤖
@어노테이션 // 기존 어노테이션은 변경하지 않음
class 클래스명 {
문장 스타일:
- 정중어 (합니다체): 「표시합니다」「관리하는 클래스입니다」
- 구두점은 「。」「、」 사용
- 한국어와 반각 영숫자 간에 반각 스페이스
- 기술 용어는 영어 표기: 「Authentication 상태」
- 각 행은 80 자 이내
3. 클래스 카테고리별 기술 예제
상태 관리 클래스 (Riverpod):
/// 수평 스와이프 제스처의 무효화 상태를 관리하는 State 입니다.
///
/// 특정 화면이나 조작 중에 수평 스와이프를 무효화할 필요가 있는 경우에
/// 사용합니다. 예를 들어 캐러셀 표시 중이나 특정 입력 중 등.
///
/// Generated by Claude 🤖
@Riverpod(keepAlive: true, dependencies: [])
class HorizontalDragGestureIgnoreState extends _$HorizontalDragGestureIgnoreState {
Widget 클래스:
/// 사용자 프로필을 표시하는 Widget 입니다.
///
/// 아바타 이미지, 사용자명, 상태 정보를 세로로 배치하고,
/// 탭 시 프로필 상세 화면으로 전환합니다.
///
/// Generated by Claude 🤖
class UserProfileWidget extends HookConsumerWidget {
4. 기존 콘텐츠 보존 규칙
- 기존 코멘트가 기준을 만족하는 경우: 그대로 보존 (신규 추가하지 않음)
- 기준: 30 자 이상이고 필수 요소 (개요·상세·마커)를 포함
- 기존 코멘트가 기준을 만족하지 않는 경우: 완전히 교체 (중복시키지 않음)
- 기존 코멘트가 없는 경우: 새로운 코멘트를 추가
보존해야 할 중요 정보:
- URL 이나 링크:
See also:로 시작하는 참조 - TODO 코멘트:
TODO(user_name):형식 - 주의사항:
주의:나Warning:등의 경고 - 사용 예:
예:나Example:로 시작하는 코드 - 기술적 제약: 성능이나 제한의 기술
Claude 마커 관리
# 마커 형식
/// 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)에 글자 수 기준 미만의 코멘트
정적 분석 및 커밋:
# 실행 결과의 기록
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 🤖"
실행 성공 기준
완료 판정: 다음을 모두 만족하는 경우에 성공
melos analyze가 PASSED- 에러 발생 수가 0
- 추가·업데이트한 코멘트가 모두 기준을 만족
부분 성공: 다음의 경우
- 에러 발생 수가 5 건 미만
- 전체의 90% 이상이 기준을 만족
실패: 다음의 경우
melos analyze가 FAILED- 에러 발생 수가 5 건 이상