kdoc

name	KDoc
description	Android 라이브러리 KDoc 주석 생성. 한·영 병기 규칙에 따라 클래스/함수/프로퍼티에 주석을 작성한다. "KDoc 작성", "주석 추가", "문서화해줘" 등의 요청 시 사용.
disable-model-invocation	true
argument-hint	파일경로 or 패키지명 or 클래스명

KDoc Skill

이 프로젝트(SimpleUI_XML)의 KDoc 주석을 작성한다. 반드시 아래 규칙을 따른다.

대상 코드 결정 우선순위

1. $ARGUMENTS 가 있으면 → 해당 파일 경로, 패키지명, 클래스명을 대상으로 한다.
2. $ARGUMENTS 가 없으면 → 현재 IDE에서 선택된 코드(ide_selection)를 대상으로 한다.
3. ide_selection 도 없으면 → 사용자에게 대상 파일 경로, 패키지명, 클래스명을 요청한 후 진행한다.

작업 순서

Step 1: 수정 전 프리체크

주석을 반영하기 전에 아래 내용을 먼저 정리한다.

• 분석 요약(5~15줄)
• 변경 대상 파일 목록
• 관련 호출부 및 영향 범위
• UTF-8 유지 및 한글 깨짐 검수 계획

Step 1 완료 후, 아래 형식으로 반드시 출력한 뒤 Step 2로 진행한다.

> 대상: {파일명}
> 변경 예정 항목 수: N개 (클래스 N, 함수 N, 프로퍼티 N)
> 영향 범위: {설명}

Step 2: 대상 파일 읽기

대상 파일을 직접 읽고, 사용자가 지정한 범위 안에서 주석이 없거나 규칙에 맞지 않는 항목을 파악한다.

범위 원칙:

• 사용자가 특정 클래스/함수/프로퍼티를 지정했으면 해당 범위만 수정한다.
• 사용자가 파일 전체를 지정한 경우에만 파일 전체 범위를 검토한다.
• 범위가 모호하면 임의로 넓히지 않고 사용자에게 먼저 확인한다.

Step 3: 주석 작성

사용자가 지정한 범위의 클래스, 함수, 프로퍼티에 한해 아래 규칙에 맞는 KDoc 주석을 작성한다.

Step 4: 검증

작성한 주석이 아래 항목을 준수하는지 확인한다.

• 영어 설명 먼저, <br><br> 후 한글 설명 순서가 맞는가
• @param, @return, @throws 한·영 병기가 적용됐는가
• 한글 끝에 <br> 마무리가 됐는가
• 코드 수정 없이 주석만 추가/수정됐는가
• UTF-8 인코딩이 유지됐는가

검증 실패 시 → Step 3으로 돌아가 해당 항목을 수정 후 재검증한다.

Step 5: 파일 반영 및 결과 요약

검증 통과 시 파일에 직접 주석을 반영하고 아래 형식으로 결과를 요약한다.

✅ 완료
- 파일: {경로}
- 적용: N개
- 미적용: {항목명} - {사유}

---

주석 규칙

기본 스타일 — 한·영 병기

• 영어 설명 먼저 작성
• <br><br> 로 줄바꿈
• 동일 내용을 한글로 반복
• 한글 끝에 <br> 로 마무리

Good

/**
 * Formats date to string.<br><br>
 * 날짜를 문자열로 변환합니다.<br>
 */

Bad

/** 날짜를 문자열로 변환 */

@param

• 첫 줄: 영어 설명
• <br><br> 후 한글 설명

/**
 * @param date Target date to format.<br><br>
 *             변환할 대상 날짜입니다.<br>
 */

@return

• 첫 줄: 반환값 영어 설명
• <br><br> 후 한글 설명

/**
 * @return Formatted date string.<br><br>
 *         변환된 날짜 문자열입니다.<br>
 */

@throws

• 첫 줄: 예외 타입 + 영어 설명
• <br><br> 후 한글 설명

/**
 * @throws IllegalArgumentException If the argument is invalid.<br><br>
 *                                  인자가 유효하지 않을 때 발생합니다.<br>
 */

클래스 문서화 템플릿 (복잡한 핵심 클래스에 선택 적용)

/**
 * Brief description.<br><br>
 * 간단한 설명.<br>
 *
 * **Why this class exists / 이 클래스가 필요한 이유:**<br>
 * - Reason 1<br>
 * - Reason 2<br><br>
 * - 이유 1<br>
 * - 이유 2<br>
 *
 * **Design decisions / 설계 결정 이유:**<br>
 * - Decision 1<br>
 * - Decision 2<br><br>
 * - 결정 1<br>
 * - 결정 2<br>
 *
 * **Important notes / 주의사항:**<br>
 * - Note 1<br>
 * - Note 2<br><br>
 * - 주의사항 1<br>
 * - 주의사항 2<br>
 *
 * **Usage / 사용법:**<br>
 * 1. Step 1<br>
 * 2. Step 2<br><br>
 * 1. 단계 1<br>
 * 2. 단계 2<br>
 */

Important notes / 주의사항 섹션은 선택 사항이며 필요 시에만 추가한다.

---

금지 항목

• 코드를 절대 수정하지 않는다 — 주석만 추가/수정한다.
• 반드시 UTF-8로 저장한다.
• 거짓말 하지 않는다.