[iOS] Quick Help 작성

* 이번 포스팅의 Quick Help는 간단한 소개가 목적이라서 복잡하고 모범적인 예시는 Swift 코드를 참고하시면 됩니다!

 

서론

 

[iOS] JeongLogger SPM 라이브러리 생성과 배포

 

저번 포스팅에서 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가 없었다면 네이밍이 두 세 배는 길어졌을거에요..ㅋㅋ

 

프레임워크, 라이브러리를 개발하신다면 꼭 도입하시는 걸 권장드립니다.

 

감사합니다!

---

아직은 초보 개발자입니다.

더 효율적인 코드 훈수 환영합니다!

공감과 댓글 부탁드립니다.