307 lines
9.1 KiB
Markdown
307 lines
9.1 KiB
Markdown
## Update Doc String
|
|
|
|
다언어 지원 docstring/코멘트를 체계적으로 관리하고, 고품질 문서를 유지합니다.
|
|
|
|
### 사용법
|
|
|
|
```bash
|
|
# 언어를 자동 검출해서 실행
|
|
「docstring 이 없는 클래스·함수에 추가하고, 기준을 만족하지 않는 코멘트를 업데이트하세요」
|
|
|
|
# 언어를 지정해서 실행
|
|
/update-doc-string --lang python
|
|
「Python 파일의 docstring 을 PEP 257 준수로 업데이트하세요」
|
|
|
|
# 특정 디렉터리의 문서 정비
|
|
「src/components/ 하위의 함수에 JSDoc 을 추가하세요」
|
|
```
|
|
|
|
### 옵션
|
|
|
|
- `--lang <en|ko>` : 문서의 기술 언어(기본값: 기존 코멘트에서 자동 판정, 없으면 en)
|
|
- `--style <스타일>` : 문서 스타일을 지정(언어 고유의 기본값 있음)
|
|
- `--marker <true|false>` : Claude 마커를 부여할지(기본값: true)
|
|
|
|
### 기본 예제
|
|
|
|
```bash
|
|
# 1. 대상 파일의 분석(프로그래밍 언어는 자동 검출)
|
|
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.dart" -o -name "*.go" -o -name "*.rs" \) | grep -v test
|
|
「docstring 이 부족한 요소(코멘트 행수 0 또는 30 자 미만)를 특정하세요」
|
|
|
|
# 2. 문서 추가(언어 자동 판정)
|
|
「특정된 요소에 언어 고유의 필수 요소를 포함하는 docstring 을 추가하세요」
|
|
# → 기존 코멘트에 한국어가 있으면 한국어로, 없으면 영어로 기술
|
|
|
|
# 3. 문서 추가(명시적으로 영어 지정)
|
|
/update-doc-string --lang en
|
|
「Add docstrings with required elements to the identified elements」
|
|
|
|
# 4. 마커 확인
|
|
「추가·업데이트한 모든 docstring 에 Claude 마커가 있는지 확인하세요」
|
|
```
|
|
|
|
### 실행 절차
|
|
|
|
#### 1. 대상 요소의 우선순위
|
|
|
|
1. 🔴 **최우선**: docstring/코멘트가 없는 요소(코멘트 행수 0)
|
|
2. 🟡 **차순위**: 기준을 만족하지 않는 요소(30 자 미만 또는 필수 요소 결여)
|
|
3. 🟢 **확인 대상**: Claude 마커가 없는 기존 코멘트
|
|
|
|
**대상 요소(언어 공통)**:
|
|
|
|
- Class/클래스 정의
|
|
- Function/함수·메서드
|
|
- Module/모듈(Python, Go)
|
|
- Enum/열거형
|
|
- Interface/인터페이스(TypeScript, Go)
|
|
|
|
#### 2. 언어별 기술 규칙
|
|
|
|
**Python (PEP 257)**:
|
|
|
|
```python
|
|
# 한국어판(기본값)
|
|
def calculate_total(items: List[Item]) -> float:
|
|
"""아이템 리스트의 합계 금액을 계산합니다.(30-60 자)
|
|
|
|
각 아이템의 가격과 수량을 곱하여, 세금 포함 합계를 반환합니다.
|
|
빈 리스트의 경우 0.0 을 반환합니다.(50-200 자)
|
|
|
|
Args:
|
|
items: 계산 대상의 아이템 리스트
|
|
|
|
Returns:
|
|
세금 포함 합계 금액
|
|
|
|
Generated by Claude 🤖
|
|
"""
|
|
|
|
# 영어판(--lang en)
|
|
def calculate_total(items: List[Item]) -> float:
|
|
"""Calculate the total amount for a list of items. (30-60 chars)
|
|
|
|
Multiplies the price and quantity of each item and returns
|
|
the total with tax. Returns 0.0 for empty lists. (50-200 chars)
|
|
|
|
Args:
|
|
items: List of items to calculate
|
|
|
|
Returns:
|
|
Total amount with tax
|
|
|
|
Generated by Claude 🤖
|
|
"""
|
|
```
|
|
|
|
**JavaScript/TypeScript (JSDoc)**:
|
|
|
|
```javascript
|
|
/**
|
|
* 사용자 프로필을 표시하는 컴포넌트입니다.(30-60 자)
|
|
*
|
|
* 아바타 이미지, 사용자명, 상태 정보를 표시하고,
|
|
* 클릭 시 프로필 상세 화면으로 전환합니다.(50-200 자)
|
|
*
|
|
* @param {Object} props - 컴포넌트의 프로퍼티
|
|
* @param {string} props.userId - 사용자 ID
|
|
* @param {boolean} [props.showStatus=true] - 상태 표시 플래그
|
|
* @returns {JSX.Element} 렌더링된 컴포넌트
|
|
*
|
|
* @generated by Claude 🤖
|
|
*/
|
|
const UserProfile = ({ userId, showStatus = true }) => {
|
|
```
|
|
|
|
**Go**:
|
|
|
|
```go
|
|
// CalculateTotal 은 아이템 리스트의 합계 금액을 계산합니다.(30-60 자)
|
|
//
|
|
// 각 아이템의 가격과 수량을 곱하여, 세금 포함 합계를 반환합니다.
|
|
// 빈 슬라이스의 경우 0.0 을 반환합니다.(50-200 자)
|
|
//
|
|
// Generated by Claude 🤖
|
|
func CalculateTotal(items []Item) float64 {
|
|
```
|
|
|
|
**Rust**:
|
|
|
|
```rust
|
|
/// 아이템 리스트의 합계 금액을 계산합니다.(30-60 자)
|
|
///
|
|
/// 각 아이템의 가격과 수량을 곱하여, 세금 포함 합계를 반환합니다.
|
|
/// 빈 벡터의 경우 0.0 을 반환합니다.(50-200 자)
|
|
///
|
|
/// Generated by Claude 🤖
|
|
pub fn calculate_total(items: &[Item]) -> f64 {
|
|
```
|
|
|
|
**Dart (DartDoc)**:
|
|
|
|
```dart
|
|
/// 사용자 프로필을 표시하는 Widget 입니다.(30-60 자)
|
|
///
|
|
/// 아바타 이미지, 사용자명, 상태 정보를 세로로 배치하고,
|
|
/// 탭 시 프로필 상세 화면으로 전환합니다.(50-200 자)
|
|
///
|
|
/// Generated by Claude 🤖
|
|
class UserProfileWidget extends StatelessWidget {
|
|
```
|
|
|
|
#### 3. 기존 콘텐츠 보존 규칙
|
|
|
|
1. **기존 코멘트가 기준을 만족하는 경우**: 그대로 보존(신규 추가하지 않음)
|
|
- 기준: 30 자 이상이고 필수 요소(개요·상세·마커)를 포함
|
|
2. **기존 코멘트가 기준을 만족하지 않는 경우**: 완전히 교체(중복시키지 않음)
|
|
3. **기존 코멘트가 없는 경우**: 새로운 코멘트를 추가
|
|
|
|
**보존해야 할 중요 정보**:
|
|
|
|
- URL 이나 링크: `See also:`, `@see`, `참조:` 등
|
|
- TODO 코멘트: `TODO:`, `FIXME:`, `XXX:` 형식
|
|
- 주의사항: `Note:`, `Warning:`, `주의:` 등
|
|
- 사용 예: `Example:`, `예:`, `# Examples` 등
|
|
- 기존의 파라미터·반환값 설명
|
|
|
|
### 언어별 설정
|
|
|
|
```yaml
|
|
# 언어별 기본 설정
|
|
languages:
|
|
python:
|
|
style: "google" # google, numpy, sphinx
|
|
indent: 4
|
|
quotes: '"""'
|
|
|
|
javascript:
|
|
style: "jsdoc"
|
|
indent: 2
|
|
prefix: "/**"
|
|
suffix: "*/"
|
|
|
|
typescript:
|
|
style: "tsdoc"
|
|
indent: 2
|
|
prefix: "/**"
|
|
suffix: "*/"
|
|
|
|
go:
|
|
style: "godoc"
|
|
indent: 0
|
|
prefix: "//"
|
|
|
|
rust:
|
|
style: "rustdoc"
|
|
indent: 0
|
|
prefix: "///"
|
|
|
|
dart:
|
|
style: "dartdoc"
|
|
indent: 0
|
|
prefix: "///"
|
|
```
|
|
|
|
### 품질 체크리스트
|
|
|
|
- ✅ **글자 수**: 개요 30-60 자, 상세 50-200 자를 엄수
|
|
- ✅ **필수 요소**: 개요·상세 설명·Claude 마커의 3 요소를 반드시 포함
|
|
- ✅ **완전성**: 역할·사용 컨텍스트·주의점을 기재
|
|
- ✅ **언어 규약**: 각 언어의 공식 스타일 가이드에 준수
|
|
- ✅ **예외**: 오류·예외의 설명(해당하는 경우)
|
|
- ✅ **정확성**: 구현을 분석하고 사실기반의 기술만
|
|
|
|
### 주의사항
|
|
|
|
**🔴 절대 금지사항**:
|
|
|
|
- ❌ 문서 코멘트 이외의 코드 변경
|
|
- ❌ 구현 세부사항에 관한 추측(사실만 기재)
|
|
- ❌ 언어 규약에 반하는 포맷
|
|
- ❌ 기존 타입 어노테이션의 삭제·변경
|
|
- ❌ 기존 코멘트와의 중복
|
|
- ❌ 테스트 파일에 글자 수 기준 미만의 코멘트
|
|
|
|
**실행과 검증**:
|
|
|
|
```bash
|
|
# 실행 결과의 기록
|
|
ADDED_COMMENTS=0
|
|
UPDATED_COMMENTS=0
|
|
ERRORS=0
|
|
|
|
# 기존 코멘트에서 언어를 자동 판정
|
|
# 한국어 문자(한글)를 검출하면 ko, 그 외는 en
|
|
DOC_LANGUAGE="en" # 기본값
|
|
if grep -r '[가-힣]' --include="*.py" --include="*.js" --include="*.ts" --include="*.dart" --include="*.go" --include="*.rs" . 2>/dev/null | head -n 1; then
|
|
DOC_LANGUAGE="ko"
|
|
fi
|
|
|
|
# 프로그래밍 언어의 자동 검출과 정적 분석
|
|
if [ -f "*.py" ]; then
|
|
pylint --disable=all --enable=missing-docstring .
|
|
elif [ -f "*.js" ] || [ -f "*.ts" ]; then
|
|
eslint . --rule 'jsdoc/require-jsdoc: error'
|
|
elif [ -f "*.go" ]; then
|
|
golint ./...
|
|
elif [ -f "*.rs" ]; then
|
|
cargo doc --no-deps
|
|
elif [ -f "*.dart" ]; then
|
|
melos analyze
|
|
fi
|
|
|
|
if [ $? -ne 0 ]; then
|
|
echo "🔴 에러: 정적 분석이 실패했습니다"
|
|
exit 1
|
|
fi
|
|
|
|
# 실행 요약의 출력
|
|
echo "📊 실행 결과:"
|
|
echo "- 문서 언어: $DOC_LANGUAGE"
|
|
echo "- 추가한 코멘트: $ADDED_COMMENTS 건"
|
|
echo "- 업데이트한 코멘트: $UPDATED_COMMENTS 건"
|
|
echo "- 에러 발생 수: $ERRORS 건"
|
|
```
|
|
|
|
### 실행 성공 기준
|
|
|
|
1. **완료 판정**: 다음을 모두 만족하는 경우에 성공
|
|
- 언어 고유의 정적 분석이 PASSED
|
|
- 에러 발생 수가 0
|
|
- 추가·업데이트한 코멘트가 모두 기준을 만족
|
|
|
|
2. **부분 성공**: 다음의 경우
|
|
- 에러 발생 수가 5 건 미만
|
|
- 전체의 90% 이상이 기준을 만족
|
|
|
|
3. **실패**: 다음의 경우
|
|
- 정적 분석이 FAILED
|
|
- 에러 발생 수가 5 건 이상
|
|
|
|
### Claude 와의 연계
|
|
|
|
```bash
|
|
# 프로젝트 전체의 분석(언어 자동 판정)
|
|
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" \)
|
|
/update-doc-string
|
|
「이 프로젝트의 docstring 을 언어별 베스트 프랙티스에 따라 업데이트하세요」
|
|
# → 기존 코멘트에 한국어가 있으면 ko, 없으면 en 으로 실행
|
|
|
|
# 명시적으로 영어 문서로 실행
|
|
/update-doc-string --lang en
|
|
"Update docstrings following language-specific best practices"
|
|
|
|
# 명시적으로 한국어 문서로 실행
|
|
/update-doc-string --lang ko
|
|
「이 프로젝트의 docstring 을 언어별 베스트 프랙티스에 따라 업데이트하세요」
|
|
|
|
# 마커 없이 실행(언어 자동 판정)
|
|
/update-doc-string --marker false
|
|
"Improve existing docstrings without adding Claude markers"
|
|
|
|
# 영어 문서, 마커 없음
|
|
/update-doc-string --lang en --marker false
|
|
"Improve existing docstrings without adding Claude markers"
|
|
```
|