iOS DocC 완전 정복 가이드: Swift 문서화를 위한 최고의 도구

iOS DocC 완전 정복 가이드: Swift 문서화를 위한 최고의 도구

1. 들어가며

Swift 개발에서 문서화는 “선택이 아닌 필수”입니다.

하지만 현실적으로 대부분의 프로젝트에서는 문서가 코드보다 뒤처지기 마련이죠.

이 문제를 해결하기 위해 Apple은 DocC(Documentation Compiler)라는 강력한 문서화 시스템을 도입했습니다.

DocC는 Xcode 13 이상부터 공식 통합되어 있으며,

/// 형태의 Markdown 기반 주석을 자동으로 분석해

HTML 기반 개발자 문서(Developer Documentation)를 생성합니다.

이 문서는 iOS 개발자가 실무에서 DocC를 활용하는 전체 과정을 단계별로 정리했습니다.

 

2. DocC란 무엇인가?

DocC(Documentation Compiler)는 Swift 소스 코드와 주석을 분석해

자동으로 문서를 생성하는 Apple의 공식 도구입니다. 

Xcode의 Help > Developer Documentation 메뉴에서 보는 Apple 공식 문서도 사실 DocC로 만들어졌습니다.

DocC의 주요 특징은 다음과 같습니다.

항목설명

Markdown 기반	기존의 Swift 문서 주석(///, /** */)을 그대로 사용
자동 문서 생성	코드의 타입, 함수, 구조체, 클래스, 프로토콜 등 자동 인덱싱
HTML 출력	Xcode 또는 웹 서버용 정적 HTML 형태로 빌드 가능
Swift-DocC 패키지 통합 가능	SwiftPM 기반 프로젝트에서도 독립적으로 실행 가능
튜토리얼(Tutorials) 작성 지원	코드 예제 + 실습 가이드 문서를 직접 포함 가능

 

3. DocC 주석 문법 기본기

DocC는 Markdown 문법 + Swift 전용 태그 조합으로 작성합니다.

예시: ViewModel 문서화

/// 사용자의 로그인 상태를 관리하는 뷰모델입니다.
/// 
/// 로그인 성공 시 `isLoggedIn` 프로퍼티가 true로 변경됩니다.
///
/// ```swift
/// let viewModel = LoginViewModel()
/// viewModel.login(username: "user", password: "1234")
/// ```
///
/// - Author: Junhyuk Jang
/// - Version: 1.0
/// - SeeAlso: `UserService`
final class LoginViewModel {

    /// 로그인 여부 상태를 나타냅니다.
    var isLoggedIn: Bool = false

    /// 로그인 기능을 수행합니다.
    ///
    /// - Parameters:
    ///   - username: 사용자 이름
    ///   - password: 사용자 비밀번호
    /// - Returns: 로그인 성공 여부
    func login(username: String, password: String) -> Bool {
        if username == "user" && password == "1234" {
            isLoggedIn = true
            return true
        }
        return false
    }
}

문서 생성전에 확인해 보려면 LoginViewModel 클래스에서 마우스 올려놓고 Option(Alt) + 마우스 왼쪽 클릭 하면 다음과 같은 화면을 볼수 있습니다.

login 함수에서 Option(Alt) + 마우스 왼쪽 클릭 한 경우

 

4. DocC 문서 생성하기 (Xcode)

(1) DocC 문서 생성

1. Xcode 메뉴 → Product > Build Documentation 선택
2. 또는 Ctrl + Cmd + Shift + D 단축키 사용
3. 빌드가 완료되면 자동으로 DocC 문서 뷰어가 열립니다.

(2) 결과 확인

문서에는 다음 항목이 자동 포함됩니다.

• 모듈 이름별 탐색 (e.g., MyAppKit, MyFeature)
• 클래스, 구조체, 열거형, 프로토콜 목록
• 각 멤버 함수/프로퍼티 설명
• 튜토리얼 및 샘플 코드 섹션 (선택적)

DocC 결과물은 Xcode 내에서 Developer Documentation Viewer로 미리보기가 가능하며,

Export 시 .doccarchive 형태로 출력됩니다.

5. DocC 파일 구조 이해하기

DocC는 .docc 확장자를 가진 디렉토리로 구성되며, 내부에는

DocumentationCatalog 역할을 하는 Info.plist와 마크다운 문서 파일이 들어 있습니다.

MyFramework/
 ┣ Sources/
 ┃ ┣ MyFramework.swift
 ┣ Documentation/
 ┃ ┣ MyFramework.docc/
 ┃ ┃ ┣ MyFramework.md
 ┃ ┃ ┣ Tutorials/
 ┃ ┃ ┃ ┗ GettingStarted.md
 ┃ ┃ ┗ Info.plist

Info.plist 예시

<?xml version="1.0" encoding="UTF-8"?>
http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>CFBundleDisplayName</key>
  <string>MyFramework</string>
  <key>CFBundleIdentifier</key>
  <string>com.arcblack.myframework</string>
  <key>CFBundleVersion</key>
  <string>1.0</string>
</dict>
</plist>

 

6. Swift Package Manager(SwiftPM) 기반에서 DocC 사용

SPM 기반 프로젝트에서는 swift package generate-documentation 명령어를 통해

DocC 문서를 터미널에서 직접 생성할 수 있습니다.

swift package generate-documentation   --target MyLibrary   --output-path ./docs   --format html

이 명령어를 실행하면 ./docs 디렉토리에 HTML 문서가 생성됩니다.

이를 GitHub Pages 등 정적 호스팅 서비스에 올릴 수 있습니다.

 

7. Tuist 기반 프로젝트에서 DocC 활용

Tuist 프로젝트에서는 tuist build 시 자동으로 DocC 통합이 가능합니다.

다만, 각 모듈별로 .docc 디렉토리를 만들어줘야 합니다.

예시:

Projects/
 ┣ Feature/
 ┃ ┣ Sources/
 ┃ ┃ ┣ HomeView.swift
 ┃ ┗ Documentation/
 ┃    ┗ HomeFeature.docc/
 ┃       ┗ HomeFeature.md

그 후 Xcode > Product > Build Documentation 실행 시 모든 모듈의 문서가 함께 빌드됩니다.

 

8. DocC 튜토리얼 작성하기

DocC의 강력한 기능 중 하나는 Tutorials입니다.

튜토리얼은 실제 코드 예제와 순차적 가이드를 제공하는 학습용 문서 형식입니다.

튜토리얼 예시

Documentation/MyFramework.docc/Tutorials/GettingStarted.md

# MyFramework 시작하기

@Tutorial(time: 10 minutes)

이 튜토리얼에서는 MyFramework의 핵심 기능을 실습합니다.

## Step 1: 프로젝트 생성

```swift
import MyFramework

let manager = UserManager()
manager.loadUsers()

 

9. DocC Export 및 배포

xcodebuild docbuild   -scheme MyApp   -destination 'generic/platform=iOS'   -derivedDataPath ./DerivedData

xcrun docc process-archive transform-for-static-hosting   ./DerivedData/Build/Products/Debug-iphoneos/MyApp.doccarchive   --output-path ./docs   --hosting-base-path MyAppDocs

 

10. DocC의 장단점

장점단점

Apple 공식 문서 생성 도구	Swift 이외 언어 지원 미약
Xcode 완전 통합	UI 커스터마이징 제약
Markdown 친화적	대형 프로젝트 빌드 시간 다소 증가
Tutorial 기능 강력	.docc 구조 이해 필요

 

11. 결론

DocC는 단순한 주석 생성기가 아니라, Swift 생태계의 공식 문서 플랫폼입니다.

Xcode와 완벽히 통합되어, 개발자 경험(DX)을 획기적으로 개선합니다.

TDD와 함께 사용하면 코드, 테스트, 문서의 3박자를 완성할 수 있습니다.