Xcode 함수 설명 작성하기 (문서화 주석)(with. symbol documentation)

안녕하세요. 

오랜만입니다.

아무래도 요즘 하고 있는 프로젝트가 있다보니 정신이 다소 없네요.

(정확히는 기껏 다만들었더니 갈아 엎자고 해서 화난...)

 

아무튼 오늘은 기분도 환기 시킬겸 

가벼운 내용을 가져왔습니다. 

 

개발하다보면 

XCode 오른쪽에 ? 버튼에 아래처럼 설명이 보이실겁니다. 

이거 많이 보셨죠?

오늘은 저희가 만든 함수도

이렇게 설명이 보이도록 만드는 방법에 대해 알아보겠습니다.

 

공식에서 자세히 나와 있습니다.

https://developer.apple.com/documentation/xcode/writing-symbol-documentation-in-your-source-files

Writing symbol documentation in your source files | Apple Developer Documentation

생각보다 간단한데 

저희가 주석을 쓸때랑 거의 비슷합니다. 

// 주석
/// 설명문

/ 하나만 더 붙이면 간단하게 가능합니다.

 

예를 들어 아래 처럼 작성하면 

 /// 테스트용 함수
    @objc public func test(a: Int ,b: Int){
        print("Help")
    }

 

옆에 아래처럼 보이게 됩니다.

생각보다 괜찮죠?

저도 이걸 공부하면서 알게된 부분인데 이런 주석을 

문서화 주석 이라고 부른다고 합니다.

 

이걸 나중에 쓰면 실제로 .doccarchive 형식의 문서로 뽑아낼 수 있는데

아마 이때문에 이렇게 부르는게 아닐까 싶습니다.  

 

참고로 저 함수를 라이브러리로 만들어서 내보내면 

사용자에게도 그대로 저렇게 보이게 됩니다.

 

그럼 어떤 종류가 있는지 알아봅시다. 

/// 테스트용 함수.
/// - Parameters:
///   - a: a.파라미터 (선언한 파라미터명과 다르면 안뜨기도 함)
///   - b: b.파라미터
/// - Returns: 결과값 설명.
/// - Summary: 함수 요약 적는곳
/// - Discussion: 열심히 설명 적는곳
/// - Deprecated: 삭제되었다면 딴거를 참고하는 문구를 넣는곳.
/// - Throws:던지기
/// - Note: 추가로 정보 적기
/// - Warning: 경고경고
/// - SeeAlso: 보통 관련 링크를 넣는곳
@objc public func test(a: Int ,b: Int){
    print("Help")
}

 

실제로 확인하면 아래 처럼 보이게 됩니다.

엄청 길죠?

여기서 필요한 것들만 사용하시면 될 것 같습니다. 

 

그리고 저렇게 줄줄이 쓰는게 힘든경우에는 아래처럼 /// 가 아니라 /**내용*/ 으로 작성이 가능합니다.

 /**
     설명
     - Warning: 주의 사항
     */

 

 

근데 이걸 어떻게 문서화하는지 궁금하신 분들을 위해 조금 더 파헤쳐봅시다. 

 

저희가 무심코 지나간 부분이 있는데 설명 아래 보시면 

Open in Developer Documentation 이라는 버튼이 있습니다.

파란글씨보이시나요?

처음 눌러주시면 아래처럼 보이실텐데 Build Documentation 눌러주시면 문서가 생성됩니다.

파란 버튼 클릭

그럼 아래처럼 저희가 실제로 아까 만들었던 함수의 설명을 볼수있습니다.

신기하죠?

 

눈치채신 분들도 있겠지만 여기 옆에 버튼을 누르시면 Export 버튼이 있습니다.

이렇게요

이거 누르시면 말 그대로 해당 문서를 내보내서 다른 분들에게 보낼수있습니다.

 

참고로 파일 형식은 앞에서 말씀드린 .doccarchive 형식으로 나오게 됩니다. 

(저거는 Xcode 로 열 수 있습니다.)

 

머리 식힐 겸 다른 걸 알아본건데 

생각보다 재밌네요.

 

그럼 오늘도 파이팅입니다~