Swift Documentation - 스위프트 코드 기반 문서화 예제들

앞서 살펴본 내용에서 소스 코드 문서화의 기초적인(것 같지만 거의 대부분인 -_-) 내용을 살펴 봤다. 이번 글에서는 좀 더 다양한 예제를 통해 어떻게 하면 문서화가 되는지를 간략히 살펴보자.

참고로 이 글에서 사용되는 예제는 앞의 글에서 썼던 Player 클래스를 그대로 이어서 사용한다. 하지만 굳이 원래 클래스 모양을 볼 필요는 없을 것 같다.

프로퍼티 문서화

아래 코드를 Player 클래스에 추가했다고 치자.

/// The Magic Point
var magicPoint: Int = 100

프로퍼티를 하나 추가했는데 이에 대한 문서를 달았다. 앞선 글에서 소개했다싶이 슬래시 3개(///)를 이용해 주석을 붙이면 문서화용 주석으로 취급된다.

물론 한줄이 아니라 여러 줄로 적어도 되고 마크다운(Markdown) 문법을 이용해서 꾸며도 된다.

좀 더 상세한 메소드 도움말

/**
 Use Good Skill
   
 - Parameters:
     - skill: The skill which to use
     - who: Someone who is target
     - consumeMP: How much consume Magic Point
   
 - Throws: If 'who' already dead, it throws some exception
   
 - Returns: Returns false if not available skill
 */
func skill(_ skill: Skill, who: Any, consumeMP: Int) throws -> Bool {
  return true
}

두 개 이상의 파라미터를 문서화 한다면 이런 식으로 굳이 파라미터 하나하나 마다 Parameter 같은 이름을 붙일 필요 없이 이런 식으로 들여쓰기를 하는 방법도 있다.

그리고 Throws 를 통해 예외사항에 대한 도움말을 작성하는 것도 가능하다.

좀 더 풍성해졌다. 폼난다. ;-)

enum의 경우

눈치를 챘다면 그냥 쓰고 싶은 대로 쓰면 대체로 문서화로 통한다는 것을 알 수 있다.

/**
 The Good Skills
 
 - firePunch: 불꽃이 일어날 정도로 뜨거운 마음을 담은 펀치
 - icePunch: 아이스크림을 먹다가 때리는 펀치
 - sweetPunch: 펀치를 가장한 따귀
 */
enum Skill {
  /**
   불꽃이 일어날 정도로 뜨거운 마음을 담은 펀치
  */
  case firePunch
  /**
   아이스크림을 먹다가 때리는 펀치
   */
  case icePunch
  /**
   펀치를 가장한 따귀
  */
  case sweetPunch
}

Skill이라는 enum 과 각 항목들에 대한 도움말이 중복으로 만드는 바보같은 짓을 했다. 그런데 원래 이 둘 중 원하는 방식을 이용해도 된다. 하지만 각 case 에 문서화 주석을 달아두면 아래처럼 각 플래그의 의미를 팝업으로 볼 수가 있다.

위의 예제는 enum 타입 자체에 관한 주석도 있기에 Skill 타입 자체를 옵션 클릭한 경우에는 또다른 팝업 모양을 볼 수 있다.

이번에는 그냥 마크다운으로 꾸민 문서가 나타났다.

어떤 방법을 사용할지, 아니면 수고를 들여 둘 다 표현할지는 개인의 자유다. 하지만 제3자가 어느 부분을 통해 레퍼런스를 파악할지는 알 수 없으니 가급적 전체적인 문서를 만들어 주는 것이 친절한 방법일 것이다.

[이전글] Swift Documentation - 스위프트 코드 기반 문서화
[관련글] 스위프트(Swift) 가이드

이 블로그 검색

Seorenn SIGSEGV