[Swift] Documentation Comments

문서화를 위해 주석을 잘 작성하는 법에 대해 알아보았습니다.

애플의 주석은 마크다운의 문법과 비슷해서 누구든 쉽게 사용할 수 있습니다.

 

 

 

---

기본 주석 규칙

1. 한 줄 주석에는 3개의 슬래시(///)를 사용합니다.
2. 여러 줄 주석에는 구분 기호(/** ... */)를 사용합니다.
3. 단락은 빈 줄로 구분됩니다.
4. 순서 없는 목록은 기호 문자(-, +, *)로 표시합니다.
5. 정렬된 목록은 숫자 뒤에 마침표( 1. ) 또는 괄호( 1) )를 사용합니다.
6. Header 앞에는 기호( # )를 사용합니다.
7. 링크와 이미지도 사용 가능합니다.

/**
    # Lists

    You can apply *italic*, **bold**, or `code` inline styles.

    ## Unordered Lists

    - Unordered item
    - Unordered item with sublist
      - Unordered subitem

    ## Ordered Lists

    1. Ordered item
        1. Ordered subitem
        2. Ordered subitem
    2. Ordered item
*/

 

작성한 주석은 아래와 같이 도움말에 추가됩니다.

도움말은 함수 및 변수 이름을 option + click 하면 나타납니다.

 

 

---

문서 항목

각 항목에 대해 도움말을 정의할 수 있습니다.

 

요약(Summary)

주석의 첫 단락은 문서의 요약으로 정의됩니다.

 

Parameter, Return and Throws

• Parameter value
  - <Parameter name>: 필드를 시작으로 매개 변수에 대한 설명을 정의합니다. 매개 변수가 여러 개일 경우에는 - Parameters:의 하위 항목으로 정의합니다.

• Return value
  - Returns: 필드를 시작으로 반환 값에 대한 설명을 정의합니다.

• Throws
  - Throws: 필드를 시작으로 발생 가능한 오류에 대한 설명을 정의합니다.

/**
 Method to open the door

 - Parameter with: Password for open the door

 - Throws: `MyError.invalidPassword`

 - Returns: Success message that the door has been opened
 */
func unlockDoor(with password: String) throws -> String {
    guard password != "1234" else {
        throw MyError.invalidPassword
    }

    return "The door is open."
}

 

/**
  Create UIColor from RGB values with optional transparency.

  - Parameters:
      - red: red component.
      - green: green component.
      - blue: blue component.
      - transparency: optional transparency value (default is 1)
 */
convenience init(red: Int, green: Int, blue: Int, transparency: CGFloat = 1) {
    self.init(red: CGFloat(red) / 255.0, 
              green: CGFloat(green) / 255.0, 
              blue: CGFloat(blue) / 255.0, alpha: trans)
}

 

---

추가적인 항목

Parameter, Returns, Throws 와 더불어 추가적으로 지원하는 항목이 있습니다.

Safety Information

- Precondition

- Postcondition

- Requires

- Invariant

- Complexity

- Important

- Warning

 

Metadata

- Author

- Authors

- Copyright

- Date

- SeeAlso

- Since

- Version

 

Notes

- Attention

- Bug

- Experiment

- Note

- Remark

- ToDo

 

 

---

Code Block

함수의 사용법을 보여주는 예제 코드 블록을 삽입할 수 있습니다.

코드 블록 삽입 방법은 2가지가 있습니다.

 

앞에 4개 이상의 공백을 줘서 삽입하는 방법입니다.

/**
 Check if string is valid email format

     "test@test.com".isValidEmail -> true

 */
var isValidEmail: Bool { get }

 

3개의 backticks(`) 또는 tildes(~) 기호로 구분 선을 만들어 줘서 삽입하는 방법입니다.

/**
 Check if string is valid email format
 
 ```
 "test@test.com".isValidEmail -> true
 ```

 */
var isValidEmail: Bool { get }

 

 

---

MARK, TODO and FIXME

기능을 의미 있고 탐색하기 쉬운 섹션으로 나눌 때 사용됩니다.

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

2개의 슬래시(//)를 사용합니다.

• // MARK:

• // TODO:

• // FIXME:

 

Dash(-) 기호를 사용하면 구분 선이 표시되서 좀 더 보기 편합니다.

• // MARK: -
• // TODO: -
• // FIXME: -

 

 

---

문서화 도구

Jazzy 라는 프로젝트의 주석을 HTML 문서로 변환해 주는 오픈 소스 유틸리티가 있습니다.

프로젝트의 코드를 문서화할 때 해보면 좋을 것 같았습니다.

gem으로 jazzy를 설치하고 프로젝트의 루트 폴더에서 jazzy 명령어를 실행하면 쉽게 문서가 생성됩니다.

$ sudo gem install jazzy
$ jazzy

 

 

---

Code Snippet

자신이 사용하기 편한 형식의 코드 조각을 만들어 보겠습니다.

 

직접 만든 형식의 코드 범위를 선택하고 우클릭하면 아래와 같은 화면과 같습니다.

Create Code Snippet 을 선택하면 아래와 같은 화면이 나옵니다.

Snippet의 이름을 정해 주고, 아래 Completion 항목에도 이름을 정해 줍니다.

Completion에 설정한 명령어는 자동 완성 기능을 사용할 수 있도록 만들어 줍니다.

Snippet에서 하얀 글자로 되어 있는 코드는 언제든 대체할 수 있는 부분을 나타내며 <# ... #> 으로 텍스트를 감싸면 추가됩니다.

<#placeholder#>
<#view:UIView#>

 

Completion 항목에 설정한 명령어를 적으면 자동 완성에 추가된 것을 볼 수 있습니다.

 

 

---

 

Reference

https://nshipster.com/swift-documentation/

Swift Documentation