이번 포스팅에서는 외부에서 우리가 만든 패키지를 어떻게 사용하는 것인지 알려주기 위한 주석인 문서화 주석에 대해서 알아보도록 하겠습니다.

문서화 주석이란?

현재 그 코드를 보고 있는 개발자만 볼 수 있는 일반적인 주석과는 다르게 문서화 주석은 퀵헬프 기능을 통해서 해당 주석이 달린 코드 (변수, 상수, 메소드, 타입)를 사용하는 곳에서 볼 수 있습니다.

Xcode에서 option키를 누르면 커서가 물음표로 바뀌는데요. 그 때 원하는 코드를 누르면 그 코드의 문서화 주석을 볼 수 있습니다. 아래 예시는 SwiftUI의 onAppear를 퀵헬프 커서로 눌렀을 때 보여지는 문서화 주석입니다.

Summary이 메소드를 간단하게 설명하고 Discussion에서 이 메소드를 사용할 때 유의할 점을, Parameters와 Return 값을 설명하는데에도 쓰이는 것을 볼 수 있습니다.

문서화 주석 만들기

한줄 주석

일반적인 주석은 한줄 주석을 달 때 “//”를 사용하지만 문서화 주석의 경우는 “///”를 사용합니다.

한줄 주석을 달면 그 내용은 Summary에 쓰이고 다음 줄은 Discussion에 쓰입니다. 줄바꿈을 하기 위해서는 주석의 한 줄을 비워두어야 합니다. 아래 예시를 참고해주세요.

/// 한줄 주석의 첫 줄은 Summary에 쓰입니다.
/// 한 줄을 띄우지 않으면 계속 Summary에 이어집니다.
///
/// 줄 바꿈을 하려면 한 줄을 띄워주세요.
/// Summary에서 줄바꿈을 하면 다음 글은 Discussion에 쓰입니다.
///
/// Discussion에서는 한 줄을 띄어도 더 이상 줄바꿈이 안됩니다.
public class SomeClass {
    public init() {}
}

여러줄 주석

일반적인 주석의 경우 여러줄 주석을 달 때 “/”로 열어서 “/”로 닫지만, 문서화 주석의 경우 “/*”로 열어서 “/”로 닫습니다.

/**
한줄 주석의 첫 줄은 Summary에 쓰입니다.
한 줄을 띄우지 않으면 계속 Summary에 이어집니다.

줄 바꿈을 하려면 한 줄을 띄워주세요.
Summary에서 줄바꿈을 하면 다음 글은 Discussion에 쓰입니다.
*/
class SomeClass {
    
}

필요한 문단 만들기

“-” + “문단 이름” + “:”을 통해서 Summary와 Discussion 말고도 다양한 문단을 만들 수 있습니다. 문단 이름은 마음대로 정할 수 있는 것은 아니고 아래처럼 정해진 문단의 이름이 있다는 점에 주의합니다.

/**
 - Author: 함수를 만든 사람
 
 - Warning: 함수를 사용할 때 주의할 점
 
 - Note: 함수에 대한 정보
 
 - Parameters:
    - param1: 함수의 인자에 대한
    - param2: 설명
 
 - Throws: 함수가 던지는 에러
 
 - returns: 함수의 리턴 값
 */
func someFunction() {
    
}

마크다운 문법 활용하기

주석 내에서는 마크다운 문법을 활용해서 다양한 요소를 넣을 수 있습니다. 특히 코드를 넣기 위해 “```” (백틱)를 사용할 수 있습니다.

나머지는 아래 예시를 참고해주세요

마치며…

TCA나 RIBs 같은 아키텍쳐를 사용하다가 보면 굉장히 문서화 주석이 잘 되어있습니다. 퀵헬프만 통해서도 많은 정보를 얻을 수 있고 대부분 그 코드를 사용하는데 있어서 큰 문제는 없습니다.

저희 회사에는 iOS 개발자가 총 4명 있는데요. 위에 언급한 아키텍쳐처럼 수만명의 iOS 개발자들이 사용하지는 않지만 이 4명의 개발자들이 모두 제가 만들고 있는 이 패키지를 사용하기 때문에 문서화 주석은 필수적이었습니다. 최대한 자세하게 적어서 다른 분들이 사용하는데 그리고 Contribute하는데도 큰 문제가 없도록 했습니다.

다음 포스팅에서는 Protocol을 사용하면서 배운 점에 대해서 포스팅해보고자 합니다.