[iOS/Swift] Quick Help 생성 방법 (문서화, 마크업, 주석)

Quick Help (설명서)

Quick Help는 코드 기능 설명서입니다.

 

간단한 예시로

 

만약 오래전 만든 코드를 지금 다시 보게 된다면 무슨 기능을 했는지 헷갈리거나

협업 시 나는 알고 있지만 다른 팀원들이 코드의 기능을 헷갈려할 때

 

이와 같은 상황에서

손쉽게 코드의 기능을 알 수 있는 일종의 설명서입니다.

 

일단 퀵 헬프가 뭔지 보고 가시죠.

 

아래 그림과 같이 코드에 대한 정보를 나타내는 창입니다.

(Summary, Discussion, Parameters...)

 

이것들을 작성하는 방법에 대해 알아봅시다.

 

 

Quick Help 단축키 사용법

일단 기본적으로 Xcode 내부에서

자동으로 퀵 헬프를 만들어주는 단축키가 존재합니다.

 

만들고 싶은 코드를 클릭한 뒤 command + option + / 를 사용하게 되면

자동적으로 Quick Help의 양식을 조건에 맞춰서 만들어 줍니다.

 

간단히 내용을 입력해 퀵 헬프를 확인해 봅시다.

이와 같이 단축키를 사용하면 간편하게 퀵 헬프를 만들 수 있습니다.

 

 

직접 만들기

Quick Help 작성은 마크업 문법을 사용합니다

 

마크업 문법으로 기능들을 문서화시켜서

코드를 손쉽게 이해하고 사용할 수 있게 도와주죠. 

 

마크업 작성에 대한 자세한 내용은 공식문서 를 참고해 주세요.

 

이와 같이 주석 생성합니다.

한 줄 주석(슬래쉬 3개)
/// 

여러줄 주석
/**
    ...
    ...
 */

 

 

마크업 기본 문법

/**
 첫 번째 줄은 Summary 부분 입니다.
 
 이 부분은 Discussion 입니다.
 
 만약,
 공백으로 줄 바꿈 하지 않으면 이와같이 윗 줄과 붙어 나옵니다.
 
 - ' - ' 글 머리 기호
 - 바로 밑 부분을 같은 기호로 사용 시 간격이 좁게 생성됩니다.
 + ' + ' 글 머리 기호
 * ' * ' 글 머리 기호
     * Tab 한 번으로 안쪽 글 머리 기호
         *   Tab 두 번으로 안쪽 글 머리 기호 (모양 변화는 세번 까지 가능)
 
 1. 번호 목록
 2. 번호 목록
     1. Tab 한 번으로 안쪽 번호 목록
 3.  번호 목록
 
 ```
 (` / ₩) 3번을 통해 코드 블록 생성
 class QuickHelpGuide
 ```

     Tab으로도 코드 블록 생성이 가능
     class QuickHelpGuide
 
 글꼴 기울기는 _언더 바 1개(\_)_ or *별표 1개(\*)* 를 사용
 
 굵은 글씨체는 __언더 바 2개(\__)__ or **별표 2개(\**)** 를 사용
 
 * [링크 생성 시 대괄호 : 대체 텍스트](소괄호 : 링크 주소 입력)
 [My Blog](https://ios-daniel-yang.tistory.com/)
 
 # h1 헤더 만들기
## h2 헤더 만들기 ... h6 까지
현재 작은 Quick Help에서는 보이지 않음 (Xcode 14.2)
하지만 Open in Developer Documentation로 들어가면 적용이 된 것을 확인 가능.
 
 기본 마크업 문법에 대해서 알아 봤습니다.
 */
 func quickHelp(name: String, index: Int) throws -> Bool {
     
     return true
 }

 

위의 코드는 이와 같이 생성이 됩니다.

 

 

기능 설명선 필드 (Callout)

퀵 헬프에서 Parameters, Returns와 같은 필드를 추가하는 방법에 대하여 알아봅시다.

 

Callouts 종류

 

👉 Algorithm/Safety Information

Precondition : 전제 조건

Postcondition : 이후에 성립되어야 하는 조건

Requires : 요구사항

Invariant : 변형성

Complexity : 복잡도

Important : 중요한 점

Warning : 경고

 

👉 Metadata

Author : 저자

Authors : 저자들

Copyright : 저작권

Date : 날짜

SeeAlso : 추가로 봐야 할 점들

Since : 생성된 때 (날짜, 버전, 운영체제 등)

Version : 버전

 

👉 General Notes & Exhortation

Attention : 주의사항 (강조사항)

Bug : 버그

Experiment : 실험

Note : 참고

Remark : 비고

ToDo : 해야 할 것

 

필드를 생성하려면 기본적으로

-, +, * 기호 중 하나를 맨 앞에 입력 후 사용합니다.

/**
 기능 설명선(Callout)의 종류
 
 Callout을 사용해보자
 
 - Parameters:
    - name: 이름을 입력해주세요.
    - index: 숫자를 입력해주세요.
 
 - Returns: true 혹은 false 값을  갖는다.
 
 - Throws: 에러가 발생할 가능성이 존재합니다.
 
 - Warning: 무단으로 글 사용시 문제가 될 수 있습니다.
 
 - Note: 문서화의 중요성
 
 - Author: Daniel
 - Date: Feb 10, 2023
 - Since: First available in Mac OS 10
 */
func quickHelp(name: String, index: Int) throws -> Bool {
    
    return true
}

 

 

MARK, TODO, FIXME

기능에 섹션을 부여하여 보다 체계적이고 탐색하게 쉽게 하는 역할을 합니다.

섹션은 소스 탐색기에서 확인할 수 있습니다.

 

참고로 Dash(-)를 추가하면 구분 선이 생성됩니다.

// MARK: - 

// TODO: - 

// FIXME: - 

 

이와 같이 사용합니다. 

// MARK: 퀵 헬프 가이드
class QuickHelpGuide {
    // MARK: - 1. 단축키
    func quickHelp() throws -> Bool {
        return true
    }
    
    // MARK: - 2. 마크업 문법
    func quickHelp(name: String) {
    }
    
    // MARK: - 3. Callout 표현 방법
    func quickHelp(name: String, index: Int) throws -> Bool {
        return true
    }
    
    // TODO: - 해야 할 작업
    func pushGitHub() {
    }
    
    // FIXME: - 고쳐야 할 작업
    func mySelf() {
    }
}

 

 

부족한 설명이지만, 조금은 이해 가셨나요?

틀린 내용이 있다면 언제든지 지적해 주시면 감사히 받겠습니다. 🫠
읽어주셔서 감사합니다 😃