Initial commit
This commit is contained in:
Zhongwei Li
202
commands/update-dart-doc.md
Normal file
202
commands/update-dart-doc.md
Normal file
@@ -0,0 +1,202 @@
|
||||
## Update Dart Doc
|
||||
|
||||
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 건 이상
|
||||
Reference in New Issue
Block a user