일 | 월 | 화 | 수 | 목 | 금 | 토 |
---|---|---|---|---|---|---|
1 | 2 | |||||
3 | 4 | 5 | 6 | 7 | 8 | 9 |
10 | 11 | 12 | 13 | 14 | 15 | 16 |
17 | 18 | 19 | 20 | 21 | 22 | 23 |
24 | 25 | 26 | 27 | 28 | 29 | 30 |
- 안드로이드 os 구조
- 안드로이드 레트로핏 crud
- rxjava disposable
- 안드로이드 라이선스 종류
- 객체
- 안드로이드 라이선스
- 서비스 vs 쓰레드
- jvm이란
- rxjava hot observable
- 플러터 설치 2022
- android ar 개발
- 안드로이드 레트로핏 사용법
- ANR이란
- 큐 자바 코드
- 안드로이드 유닛 테스트
- 자바 다형성
- jvm 작동 원리
- 안드로이드 유닛테스트란
- 스택 큐 차이
- 안드로이드 유닛 테스트 예시
- Rxjava Observable
- 클래스
- 2022 플러터 설치
- 스택 자바 코드
- ar vr 차이
- 2022 플러터 안드로이드 스튜디오
- 멤버변수
- rxjava cold observable
- android retrofit login
- 서비스 쓰레드 차이
- Today
- Total
나만을 위한 블로그
[Kotlin] KDoc 주석이란? 본문
마냥 기능을 작동시키는 코드만 짤 수는 없다. 필요하다면 어떤 클래스, 함수가 무슨 일을 하고 왜 이걸 만들었는지에 대한 주석을 써야 할 수 있다.
주석에 대해 찾다가 이 글까지 본 사람이라면 알겠지만, 코틀린의 주석은 3종류 있다.
- 한 줄 주석(Line comment)
- 블록 주석(Block comment)
- KDoc 주석
이 중에서 KDoc 주석에 대해 정리하려고 한다. 먼저 자바를 공부했던 사람이라면 자바독 주석을 알 텐데, KDoc 주석이 바로 자바독 주석이다. 코틀린이라 앞에 'K'가 붙은 걸 빼면 모든 게 자바독 주석과 일치한다.
하지만 자바를 공부한 적 없고 코틀린부터 시작했다면 아래 공식문서부터 보자.
https://kotlinlang.org/docs/kotlin-doc.html
코틀린 코드를 문서화하는 데 사용되는 언어를 KDoc이라고 한다. 본질적으로 KDoc은 자바독의 블록 태그 구문과 인라인 마크업을 위한 마크다운을 결합한다
자바독과 마찬가지로 KDoc 주석은 "/**"로 시작하고 "*/"로 끝난다. 주석의 모든 줄은 별표로 시작할 수 있으며 주석 내용의 일부로 간주되지 않는다. 관례적으로 첫 단락은 요약 설명이고 다음 텍스트는 자세한 설명이다. 모든 블록 태그는 새 줄에서 시작하고 @로 시작한다. 아래는 KDoc을 사용해 문서화된 클래스 예시다
/**
* A group of *members*.
*
* This class has no useful logic; it's just a documentation example.
*
* @param T the type of a member in this group.
* @property name the name of this group.
* @constructor Creates an empty group.
*/
class Group<T>(val name: String) {
/**
* Adds a [member] to this group.
* @return the new size of the group.
*/
fun add(member: T): Int { ... }
}
@param : 함수의 타입 매개변수, 클래스, 프로퍼티를 문서화한다. 설명과 매개변수명을 더 잘 구분하기 위해 원한다면 매개변수명을 대괄호로 묶을 수 있다. 따라서 아래의 두 구문은 동일하다
- @param name description / @param[name] description
@return : 함수의 리턴값을 문서화
@constructor : 클래스의 기본 생성자를 문서화
@receiver : 확장 함수의 리시버 변수를 문서화
@property_name : 특정 이름을 가진 클래스의 프로퍼티를 문서화. 이 태그는 주 생성자에서 선언된 프로퍼티를 문서화하는 데 사용할 수 있다
@throws_class, @exception_class : 메서드에 의해 발생할 수 있는 예외를 문서화. 코틀린에는 확인된(checked) 예외가 없으므로 가능한 모든 예외가 문서화될 거라는 기대도 없다. 하지만 클래스 사용자에게 유용한 정보를 제공하려면 이 태그를 사용한다
@sample : 요소를 사용할 수 있는 방법의 예시를 보여주기 위해 어떤 정규화된 이름을 가진 함수 본문을 현재 주석에 포함한다
@see : 문서의 참고 항목 블록에 지정된 클래스 or 메서드의 링크를 추가
@author : 문서의 작성자 명시
@since : 문서화하는 요소가 도입된 소프트웨어 버전을 지정
@suppress : 생성된 문서에서 요소를 제외한다. 공식 API의 일부는 아니지만 외부에서 볼 수 있어야 하는 요소에 사용할 수 있다
공식문서에서 말하는 KDoc 주석에서 사용할 수 있는 문법은 위와 같다.
아래는 미디엄에서 가져온 또 다른 KDoc 주석 예시다.
/**
* Calculator class which has a add method
*
* @author by Ali Shobeyri
* @see <a href="https://google.com">google link</a>
*
* @property battery is the percentage of how much charges the calculator has
*
*/
class Calculator(val battery : Float) {
/**
* @param value_1 is first input
* @param value_2 is second input
*
* @return this function return [value_1] + [value_2]
*
* @throws Exception if the battery is 0%
*/
fun add(value_1: Int, value_2: Int): Int{
if(battery > 0) return value_1 + value_2
else throw Exception("No Charge")
}
}
위 코드를 IDE에 붙여넣고, 주황색 책 아이콘을 클릭하면 아래처럼 표시된다.
그러나 직접 "/**"를 입력하고 엔터 친 다음, 저것들을 모두 작성하기는 번거롭다.
그래서 완전히는 아니지만 번거로움을 어느 정도 해소할 수 있는 인텔리제이 플러그인이 있다. kdoc-generator라는 플러그인이다.
설치 후 재시작할 필요도 없고, 함수 시그니처를 모두 작성한 다음 KDoc 주석을 작성하면 플러그인이 자동으로 매개변수의 개수만큼 @param을 만들어 준다.
참고한 사이트)
https://medium.com/@drflakelorenzgerman/documentation-with-kdoc-for-kotlin-android-a93c99dfe74
https://dev-jewon.tistory.com/21
'개인 공부 > Kotlin' 카테고리의 다른 글
[Kotlin] 멀티 쓰레딩이란? synchronized란? (0) | 2023.11.09 |
---|---|
[Kotlin] 컬렉션 필터링 (filter, any, none, all) (0) | 2023.11.08 |
[Kotlin] 함수형(SAM) 인터페이스란? (0) | 2023.09.19 |
[Kotlin] 에러 처리 Best Practices (0) | 2023.09.08 |
[Kotlin] 코루틴의 취소와 suspendCancellableCoroutine (0) | 2023.08.06 |