[iOS] Xcode 주석으로 자동 개발 문서 만드는 방법 (jazzy)

 

 

작성한 주석을 사용해서 자동으로 개발 문서를 만들어주는 jazzy라는 방법을 소개합니다.

swift와 objective-c 모두 지원하며

swift는 비교적 간단하고, objective-c는 조금 귀찮은 작업이 필요합니다.

objective-c 사용법으로 여러가지 방법이 있는데 그 중 가장 간단한 방법을 사용했습니다.

 

 

참고) jazzy github 주소

https://github.com/realm/jazzy

realm/jazzy

 

0. 주석 추가

jazzy는 마크업 문법 형식에 따라 입력한 주석만 문서화가 됩니다.

설명이 필요한 클래스와 함수는 아래 형식에 맞춰 주석을 추가한 후 문서화를 하도록 합니다.

자동 문서화 주석 코드 추가: command + option + / 

 

• swift

/// 테스트 함수 설명   /// - Parameter name: 파라미터 설명   /// - Returns: 리턴 설명   func testFunc(name: String) -> Int

 

• objective-c

objective-c는 @return이 자동으로 추가되지 않는다.. 일단 직접 입력했습니다.

참고) 주석은 구현파일이 아닌 헤더파일에 입력해야함!!!

/// 테스트 함수 설명 /// @param name 파라미터 설명 /// @return 리턴 설명 -(int)testFunc:(NSString*)name;

 

 

1. jazzy 설치

터미널에서 입력

$ sudo gem install jazzy

 

 

2. 터미널에서 프로젝트 경로로 이동

$ cd 프로젝트 경로

 

 

3. 문서 생성

 

• swift

$ jazzy --min-acl internal

 

• objective-c

objective-c는 swift처럼 자동으로 프로젝트를 문서화하지 못합니다.

그래서 필요한 것이 umbrella header 파일입니다.

헤더 파일 생성후, 문서화할 클래스들을 import합니다.

해당 헤더 파일을 umberlla header로 사용합니다.

$ jazzy --objc --umbrella-header 프로젝트폴더/Umbrella header 파일.h ex) $ jazzy --objc --umbrella-header JazzyTest/UmbrellaClass.h

참고) 프레임워크에서 UmbrellaClass에 import 시 주의점

#import <FrameworkName/ClassName.h> 와 같은 형식으로 import하면 안되고

#import "ClassName.h" 와 같은 형식으로 import 해야함

 

 

4. 문서화 완료

문서 생성이 완료되면 터미널에 아래와 같이 출력됩니다.

jam out ♪♫ to your fresh new docs in `docs`

프로젝트 폴더에 docs 라는 폴더가 생깁니다.

해당 폴더에서 index.html을 열어 문서를 확인하면 됩니다.

 

 

5. 생성된 문서 샘플

결과물은 이런 느낌으로 나옵니다. (어딘가에서 가져온 샘플)

: https://realm.io/docs/swift/latest/api/

 

아래는 참고 스크린샷

• swift

• objective-c

 

*참고사항)

objective-c에서 문서화 시, import하는 파일들이 umberlla class가 있는 폴더에 있어야합니다.

 

 

끝