[Swift DocC] 문서 만들기 01 - Reference 만들기

Swift DocC

 

이번 포스팅에서는 Swift DocC를 사용해 예제 프로젝트에 대한 문서를 만들어 보겠습니다. Swift DocC가 무엇인지 아직 모르신다면 지난 글을 참고해주세요.

 

[Swift DocC] 개념과 기능 (with WWDC)

 

바로 시작!

 

 

프로젝트 소개

DocC 예제를 위해 전자기기 View를 만드는 간단한 예제 프로젝트를 하나 만들었습니다.

 

 

총 4개의 세트가 있고, 하나의 세트에 4개의 전자기기가 들어갑니다.

 

 

코드로 확인해보겠습니다. enum타입 Electronics은 1부터 4까지 4개의 타입을 가집니다.

 

enum Electronics:CaseIterable {
    
    case one
    case two
    case three
    case four
    
    var setComponents: [String] {
        switch self {
        case .one: return ["iphone", "ipad", "applepencil.gen2", "applewatch"]
        case .two: return ["iphone.gen3", "airpodspro.chargingcase.wireless", "macbook", "magicmouse"]
        case .three: return ["4k.tv", "appletvremote.gen2", "appletv", "hifispeaker"]
        case .four: return ["display", "macpro.gen3", "keyboard", "homepod"]
        }
    }
}

 

 

ElectronicsView는 Electronics를 인자로 받고, 반복문을 통해 setComponents에 해당하는 String을 리턴해줍니다.

 

import SwiftUI

struct ElectronicsView: View {
    
    @State var electronics: Electronics
    
    var body: some View {
        
        HStack {
            ForEach(electronics.setComponents, id: \.self) { element in
                Image(systemName: element)
                    .font(.largeTitle)
            }
        }
        
    }
}

 

preview로 확인하면 아래와 같습니다.

 

one.setComponents preview

 

 

ContentView에서는 Electronics를 순회하며 4가지 세트에 대한 ElectronicsView를 리턴합니다.

 

struct ContentView: View {
    var body: some View {
        VStack {
            
            ForEach(Electronics.allCases, id: \.self) { electronic in
                ElectronicsView(electronics: electronic)
                    .padding()
            }
            
        }
        .padding()
    }
}

 

preview로 보면 아래와 같습니다.

Content View

 

 

전자기기 세트 View를 리턴해주는 이 프로젝트에 대한 문서를 만들어 보겠습니다.

 

 

DocC 살펴보기

먼저 Build Documentation (Ctrl + Shift + Cmd + D)를 통해 기본 문서를 확인해보겠습니다.

 

 

빌드가 완료되면 자동으로 문서창이 뜹니다.

 

기본 Documentation

 

제가 만든 struct와 enum 타입이 있네요. ElectronicsView를 살펴보겠습니다.

 

ElectronicsView

기본적인 코드, 이니셜라이져, 프로퍼티를 확인할 수 있습니다. 현재 View 프로토콜을 채택하고 있기 때문에 Conforms To에 SwiftUI.View가 떠있는 것을 확인할 수 있습니다.

 

 

다음으로 enum 타입 Electronics를 살펴보겠습니다.

 

enum타입의 case를 확인할 수 있고, 인스턴스 프로퍼티를 확인할 수 있습니다. for문을 돌기 위해 CaseIterable을 채택해주었는데 그와 관련된 CaseIterable, Equatable, Hashable, Sendable도 확인할 수 가 있습니다.

 

 

case에는 아직 아무 것도 없네요.

 

 

인스턴스 프로퍼티에도 코드만 있고 아직 설명은 없습니다.

 

 

이제 설명을 추가해보겠습니다.

 

 

 

 

DocC로 문서 Reference 만들기

DocC에는 Article, Reference, Tutroials이 있습니다. 이번 글에서는 코드를 설명해주는 가장 기본적인 문서 - Reference를 만들어보겠습니다.

 

만드는 방법은 어렵지 않습니다. 설명하고 싶은 코드 위에 주석을 사용해서 작성해줍니다. 이 때 2개짜리가 아닌 3개짜리 /// 주석을 사용하면 쉽게 문서를 만들 수 있습니다.

 

 

 

문서(Documentation)을 빌드하고 확인하면 설명이 추가되어 있습니다.

 

기본 설명

 

첫 번째 줄 주석은 한 줄 설명입니다. 타입 혹은 메소드에 대한 간단하면서 직관적인 설명을 적어주면 됩니다.

 

한 줄 설명에서 한 줄 띄고 작성하면 OverView를 작성할 수 있습니다.

 

 

 

 

OverView까지 잘 나오는 것을 확인했습니다.

 

 

지금까지 Documentation을 Build 해주었는데요. 수정할 때마다 빌드하는 건 귀찮으니 documentation preview 기능을 사용하겠습니다.

 

 

Assistatnt를 선택해줍니다.

 

 

 

 

Assistatnt를 선택하면 Counterparts가 기본으로 선택되었습니다. 클릭해서 Documentation Preview로 변경해줍니다.

 

 

 

변경해주면 preview를 확인할 수 있습니다!

 

커서 위치에 따라 preview가 달라집니다. 위 이미지에서 커서가 첫 번째 라인의 Electronics 주석에 있기 때문에 Electronics 문서가 나옵니다.

 

만약 10번 째 라인으로 이동하면 setComponents 문서를 확인할 수 있습니다.

 

 

 

이제 case에 대해서도 문서를 만들겠습니다.

 

 

preview에서는 문서의 Topics를 확인할 수 가 없습니다. 현재 Xcode 15.0 beta2 버전을 사용하고 있기 때문에 추후 정식 버전 지원을 확인해봐야겠습니다.

preview

 

Build를 한 Documentation

 

 

CaseIterable을 채택하면 case 순서가 코드 작성 순서와 동일한데, 현재는 enum 문서라 독립적으로 분류되서 순서가 보장되지는 않는 것 같습니다. 

 

 

 

 

case도 enum 타입과 마찬가지로 첫 번째 줄이 요약 설명입니다. 한 라인 띄고 Discussion을 작성할 수 있습니다.

 

 

Discussion에서 줄바꿈

만약 Discussion에서 줄바꿈을 하고 싶으면, 한 라인 띄고 작성하면 됩니다.

 

 

Electronics 타입 표현하기

 

특정 타입을 작성하고 싶다면 Markdown 문법고 동일하게 ``(백틱)으로 감싸주면 됩니다.

 

Electronics는 코드로 인식돼서 다른 글씨체로 나온다.

 

 

Markdown 문법을 지원하기 때문에 Swift 코드도 추가해줄 수 있습니다.

 

Markdown 코드 문법 사용

 

 

Swift 예시 코드 확인 가능

 

 

Option 키를 누른 상태에서 코드를 클릭하면 문서 요약본을 확인할 수 있습니다.

 

 

 

Open in Developer Documentaion을 클릭하면 문서로 이동해서 연관된 타입 등 더 자세한 확인할 수 있습니다.

 

 

 

정리

코드 설명을 해주는 Reference 문서(Documentation)를 만들어보았습니다. 평소에 주석을 작성해서 만드는 방법이 생소하진 않았지만 개발자 문서나 preview를 통해 확인할 수 있는 것이 새로웠던 것 같습니다.

 

애플 공식문서가 어떻게 작성되어 있는지 확인하며 문서가 잘 작성되었는지 확인하는 공부가 필요해 보입니다 😅

 

 

이상 Reference 만들고 Documentation 확인하기 끝

 

끝

.

끝

 

 

다음 글 - Article 만들기

 

[Swift DocC] Article(설명 글) 만들기

 

 

 

출처

Meet DocC documentation in Xcode - WWDC21 - Videos - Apple Developer

 

What's new in Swift-DocC - WWDC22 - Videos - Apple Developer

 

Create rich documentation with Swift-DocC - WWDC23 - Videos - Apple Developer