[Xcode] 문서 주석(Doc comments) 작성하기, DocC 만들기

[Xcode] How to write Doc comments and create DocC(Documentation Catalog).

문서 주석을 작성해야하는 이유

---

저는 위와 같이 문서 주석을 상당히 좋아하고 열심히 작성하는데요, 그 이유는 다음과 같습니다.

 

1. Quick Help를 통해 다른 소스파일에서 필요한 내용을 확인하기 위해

option+클릭/Xcode 우측의 quiz help 창

이런식으로 필요한 내용들을 적어두면 사용할때마다 편리하게 내용을 볼 수 있습니다.

또한 이렇게 개별적인 변수에 ///주석을 작성하면 어떤 의미인지도 쉽게 확인할 수 있어서 개발 편의성이 상당히 올라갑니다!

 

2. 다른사람의 참고를 위해서

당연한 이야기지만, 다른 사람이 해당 코드를 쓸 경우에 이해를 돕기 위해서 작성합니다. 최대한 자세히 작성할수록 이해와 사용이 편하겠죠? 이때 문서 주석을 사용하면 다양한 키워드나 마크다운 문법을 이용해서 가독성 좋은 주석을 달 수 있습니다.

 

 

문서 주석 작성하는 법

---

/// comment

/**
comment
*/

문서 주석은 위의 두 방법으로 작성할 수 있습니다. 슬래시 세개나 /** */안에 작성하는 것으로 문서 주석을 만들 수 있습니다. 

 

클래스, 열거형, 구조체, 함수, 변수 등에 문서 주석을 작성할 수 있으며, 위에서 가장 가까운 문서 주석이 대상의 문서 주석으로 인식됩니다.

 

 

문서 주석 키워드

---

문서 주석의 장점은 단순히 긴 글을 쓰는 것이 아니라 키워드를 통해 섹션을 나눌 수 있다는 점입니다.

/// Sumarry
///
/// Discussion/Overview
///
/// - Parameters:
///    - [param]: [description]
/// - Returns: [description]
/// - Warning: [description]
/// - Author: [name]
/// - Version: [version number]
/// - Note: [note message]
/// - Tip: [tip message]
/// - Todo: [todo message]

- Summary: 가장 상위 첫줄로, 요약 문구를 작성합니다.

- Discussion: Summary에서 한줄 띄고 작성하는 부분부터는 Discussion부분이 됩니다.

 

그 이후에 "대쉬(-) 키워드" 형식으로 작성하면 아래와 같이 Xcode에서 굵은 글씨로 키워드를 구분해 줍니다.

 

소스파일부분에선 굵은글씨 처리가 잘 안될때도 있더라구요 ㅎㅎ;;

 

대략적으로 사용 가능한 키워드는 ⬇️에 정리해두었습니다.

Safety Information

- Precondition

- Postcondition

- Requires

- Invariant

- Complexity

- Important

- Warning

 

Metadata

- Author

- Authors

- Copyright

- Date

- Since

- Version

 

Notes

- Attention

- Bug

- Experiment

- Note

- Remark

- ToDo

- Tip

 

만약 자신만의 키워드를 사용하고 싶다면

> Keyword: description

이렇게 사용하시면됩니다!

 

💡 문서 주석 단축키는 option+cmd+/ 입니다. 주석을 작성하고자 하는 대상에 포인터를 놓고 단축키를 누르면 바로 위쪽에 문서 주석을 추가해줍니다. 메서드 같은 경우는 파라미터와 리턴을 자동으로 채워주므로 정말 유용합니다!

 

문서 주석 마크다운

---

Discussion부분에는 마크다운을 이용해 작성할 수 있습니다.

/// **bold**
/// ~~cancle~~
/// _italic_
/// `keyword`
///
/// ```swift
/// code
/// ```
/// - dot
///
/// 1. one
/// 2. two
///
/// Table  | Description
/// --- | ---
/// `row1`| This is row1
/// `row2`| This is row2
///
/// \* escaping

사실 헤딩(#, ##, ###)도 작성할 수 있는데, 이걸 작성하면 헤딩 이후부터는 Quick help에서 안보이게 되더라구요. 그래서 이 부분은 DocC부분에서 다시 언급하겠습니다.

 

+참조

그 외에도 백틱을 두번쓰면 앱 내의 요소를 검색해 참조를 작성할 수 있습니다. 메서드명이나 클래스명이 잘 기억나지 않아도 정확히 작성할 수 있습니다. 또한 다음 언급할 Documentation에서 바로가기가 연결되는 아주 유용한 기능입니다.

 

Build Documentation

---

문서 주석의 또 하나의 장점은, 그 자체로 개발 문서가 됩니다. Xcode의  Build Documentation 기능을 이용하면 마치 애플 공식문서처럼 개발 문서를 만들 수 있습니다.

 

Xcode > Product > Build Documentation을 클릭해주세요.

 

그럼 문서 주석을 공식문서처럼 정리해서 보여줍니다. 해당 프로젝트에서 작성한 모든 요소와 주석에 대해서 빌드되므로 애플 공식 문서처럼 앱의 공식 문서를 만들 수 있습니다. 너무 좋죠

✅ Xcode 우측 Quick Help 패널 하단에 Open in Developer Documentation를 클릭하면 위와 같은 문서 창을 통해 문서 주석을 확인할 수 있습니다.

✅ 아까 헤딩(#, ##, ###)을 사용하면 Quick Help에서는 보이지 않는다고 했는데, 이렇게 Documentation으로 빌드하면 전부 보이게 됩니다. 문서 주석에 헤딩을 사용하고 싶으시다면 참고해주세요!

 

 

Documentation Catalog(DocC)

---

또한 Xcode는 문서화에 대해서 다른 기능도 제공합니다. 문서 주석을 이용해서 빌드하는 것이 아니라 아예 새로운 페이지로 문서를 작성할 수도 있습니다. 

1. Xcode > File > New > File 을 클릭해줍니다.

 

2. 스크롤을 내려 Documentation Catalog를 찾아 추가해줍니다.

 

3. 그럼 Documentation 폴더가 추가되고, 마크다운 문법 예시가 있는 파일(.md)이 생깁니다.

md파일이므로 기본적인 마크다운 문법 모두 사용 가능합니다.

 

4. 내용을 수정한 후에 다시 빌드합니다.

그럼 아래와 같이 Articles에 문서가 추가된 것을 확인하실 수 있습니다.

✅ 사진은 같이 생성된 Resources 폴더에 넣어주면 됩니다.

 

DocC 종류

---

애플에서는 여러 종류의 DocC를 제공하고 있으므로, 상황에 맞게 선택해 사용할 수 있습니다.

 

Article

기본적인 형식의 마크다운 템플릿입니다.

 

맨 첫줄에 heading1을 쓰고 백틱 2개로 앱이름을 작성해주면 앱 자체에 대한 문서, 랜딩 페이지를 만들 수 있습니다.

 

Empty 

Article과 동일한 md파일이지만 형식없이 비어있는 파일이 생성됩니다.

 

Tutorial

튜토리얼을 작성할 수 있는 템플릿입니다. 

 

이때 꼭 Tutorial Table을 하나 이상 작성해서 연결해주어야합니다.

 

튜토리얼 파일을 생성하면 아래와 같은 파일이 생깁니다.

이를 적당히 채워주고 빌드해보았더니 이런 예쁜 튜토리얼이 완성되었습니다. 애플 공식 튜토리얼처럼 이미지 애니메이션도 됩니다 👍

 

Extension

Class등에 문서 주석으로 달아놓았던 부분에 추가적인 문서를 작성할 수 있는 템플릿입니다.

 

이렇게 헤딩1 ``앱이름/대상 이름``을 작성한 후 밑에 내용을 작성하면 문서 주석 내용 아래쪽으로 이어서 문서가 작성됩니다. 

 

+Link

문서 안에서 다른 문서에 대한 링크를 거는 문법입니다.

- <doc:문서 이름>

 

+ Topics 오버라이드

## Topics를 오버라이드 하면 컨텐츠 아래쪽 부분인 Topics부분도 커스텀할 수 있습니다.

 

Topics는 문서의 계층을 의미합니다. 따라서 Topics 아래에 heading3로 작성한 헤딩들은 그룹명이 되고 문서창 왼쪽 네비게이터에 굵은 글씨로(ex.Essential) 나타나게 됩니다. 따라서 Topics에 문서 링크를 사용하면 하위 문서들을 구분하고 계층화할 수 있습니다.

 

md파일에 Topics를 오버라이드하고 doc 링크를 연결하면 아래와 같이 아이콘이 바뀌면서 링크된 페이지들의 상위 페이지처럼 사용할 수 있습니다.

✅ Topics 오버라이드는 랜딩페이지와 하위 페이지 어디서든 사용할 수 있습니다. Extension에서도 가능합니다.

 

DocC빌드 설정

---

Build Settings에서 Build documentation During 'Build' 설정을 YES로 바꿔주면 앱을 시뮬레이터에서 빌드할 때 Document도 자동으로 빌드하도록 설정할 수 있습니다.

Doc 빌드 단축키가 shift + control + command + D 라서 매우 복잡하므로 이 설정도 상당히 유용할 것 같습니다.

단, 이 설정을 추가하면 빌드 속도가 느려지니 염두에 두고 사용해주세요!

 

 

마치며

---

Xcode 기본 설정 자체가 정말 좋은 것 같습니다. 일반 주석에 MARK: - 문법도 그렇고 문서 주석의 문법도 그렇고 다른 IDE로 가면 은근 불편하더라구요. ㅎㅎ

 

 

읽어주셔서 감사합니다.

 

ref.

문서 주석 키워드 참고

애플 Documentation 공식 문서