* 이번 포스팅의 Quick Help는 간단한 소개가 목적이라서 복잡하고 모범적인 예시는 Swift 코드를 참고하시면 됩니다!
서론
[iOS] JeongLogger SPM 라이브러리 생성과 배포
라이브러리 준비 라이브러리를 직접 만들고, SPM을 직접 배포해 봅시다. 라이브러리는 모든 프로젝트에서 사용되는 Log 기능으로 만들어볼건데요. 이에 몇 가지 주의점이 있습니다. 혹시 라이브
jeong9216.tistory.com
저번 포스팅에서 JeongLogger라는 SPM 라이브러리를 만들고 배포까지 진행해보았는데요.
오늘은 Quick Help라는 것을 추가해서 라이브러리 퀄리티를 높여보겠습니다.
이게 꼭 필요한가? 싶으신 분들을 위해 미리 Quick Help 적용 차이를 보여드리겠습니다.
Quick Help 적용 전에는 메서드 원형만 확인이 가능했습니다.
Quick Help를 적용한 뒤에는 Summary를 통해 어떤 메서드인지 알 수 있고,
Parameters를 통해 파라미터 설명도 볼 수 있네요.
여기엔 Return 값이 없지만 Return 설명도 볼 수 있습니다.
Quick Help
Xcode에서 클래스, 메서드 등에 Option + 클릭을 하면 설명이 뜨는게 바로 Quick Help 입니다.
역할, 파라미터, 리턴에 대한 설명을 라이브러리 사용자에게 제공하는 기능인데요.
라이브러리 개발자는 메서드명, 파라미터명으로 표현하기 힘든 자세한 내용을 Quick Help를 통해 제공할 수 있고,
라이브러리 사용자는 보다 명확하고 자세한 사용법을 확인할 수 있습니다.
라이브러리에서 명확한 네이밍은 필수적인데
저희처럼 영어가 모국어가 아닌 사람은 영어 표현에 한계가 있어서
조금이라도 큰 라이브러리를 제작한다면 이 Quick Help를 꼭 도입하는게 좋습니다.
Quick Help 작성 방법
Quick Help는 라이브러리 프로젝트에 작성해야 합니다.
Quick Help를 추가하고 싶은 메서드 위에 작성합니다.
(설명은 메서드라고 했지만 클래스, 구조체, 열거형 등 모든 곳에 추가가 가능합니다.)
Summary
/// Summary/// 를 작성한 후 바로 글을 작성하면 Summary로 표시됩니다.
Summary는 메서드의 설명을 작성하면 되는데요.
위 사진에서 Summary는 "로그 출력" 입니다.
Parameters
///- Parameters:
/// - param1 : param1 설명
/// - param2 : param2 설명파라미터 설명은 Parameter 또는 Parameters로 작성하면 됩니다.
Parameter로 작성하면 한 줄로 작성해도 되지만,
Parameters로 작성한다면 위 코드처럼 탭 구분을 해야 합니다.
이를 이용해 Enum의 연관값 Quick Help도 작성할 수 있습니다.
/// Enum Description
enum Enum {
/// enum1 Description
/// - value1: value1 Description
/// - value2: value2 Description
case enum1(value1: Int, value2: String)
/// enum2 Description
case enum2
}
Returns
///- Returns: 반환 값 설명반환 값에 대한 설명도 적을 수 있습니다.
마무리
저도 처음에는 Quick Help는 굳이..?라는 생각을 했습니다.
Swift 코드만 보더라도 길게 작성된 Quick Help 때문에 실제 코드가 안 보이는 경우도 있잖아요..?
근데 프레임워크, 라이브러리는 사용하는 입장을 고려해야 하더라고요.
"지금 당신이 쓰려는건 이런 역할이고,
이러이러한 파라미터를 넘겨주면
저러저러한 반환 값을 받을 수 있습니다."
라는 설명을 전달해주는 것이 Quick Help의 역할이기 때문에
없어서는 안 될... 필수적인 존재라는 걸 배웠습니다.
또, 개발하는 입장에서도 Quick Help가 없었다면 네이밍이 두 세 배는 길어졌을거에요..ㅋㅋ
프레임워크, 라이브러리를 개발하신다면 꼭 도입하시는 걸 권장드립니다.
감사합니다!
아직은 초보 개발자입니다.
더 효율적인 코드 훈수 환영합니다!
공감과 댓글 부탁드립니다.