누군가에게 알려주기 보다는 나 스스로 정리 하며 언젠가 다시 사용할 때를 대비하는 글을 작성할것이다.

참고자료 : Markup Formattion Reference

시작

시작글

나는 개인적으로 코드를 짜거나 보면서 문서화를 하는걸 선호하는 편이고 그렇게 하고자 노력을 많이 하는데 따로 Pages 나 Numbers 같은걸 켜서 하기에는 번잡스럽고 귀찮기도 해서 Xcode의 Quick Help 기능을 많이 사용한다.

그래서 어떻게 하면 조금 더 프로답게? 작성을 할 수 있는 방법이 뭐가 있을까 알아보다가 알게된 것들을 이곳에 적어보려 한다.

Quick Help

Quick Help(이하 퀵헬프)는 Xcode 내부에서 2가지 방법으로 확인을 할 수 있다.

1. 확인을 원하는 오브젝트위에 커서를 옮기고 Inspector 탭의 Show Quick Help inspector 에서 확인 가능

2. Option 키를 누르면서 확인을 하고 싶은 오브젝트를 클릭을 해서 확인 가능

• 개인적으로 퀵헬프 확인을 위해서는 1번의 방법을 더 많이 사용을 하는 편이다.

분석

Markup Functionality

퀵헬프는 마크업으로 작성을 할 수 있다. 마크업에 대한 정보는 맨 위의 참고자료를 확인하면 조금 더 자세하게 알 수 있을것이다.

참고자료에서 Functionality 라는 항목이 존재하는데 .swift 또는 .playground 에서 사용을 할 수 있는 항목 들에 대해서 구분해서 작성을 해놓았다.

해당 표에 적혀 있는 기능들 중에서 나는 playground 에서만 사용이 된다고 적힌것은 제외를 하고 실험을 해봤다.

• 목록
  

기초

퀵헬프는 코드내에 직접 기록하는 방식이고 원하는 오브젝트 위에 /// 나 /** (퀵헬프 내용) */ 같이 블럭으로 묶어서 만든다.

아래와 같은 방법으로 생성한다.

/// number는 상수이다.
///
/// number는 항상 0이다.
let number: Int = 0

/** 
number는 상수이다.

number는 항상 0이다.
*/
let number: Int = 0

또는

/** number는 상수이다.

number는 항상 0이다. */
let number: Int = 0

보면 알다시피 맨 위의 내용은 항상 Summary 부분에 입력이 되며 한 줄 비우고 아래에 써지는 내용은 Discussion 부분에 입력이 된다.

대충 이해하기 쉽게 적어보자면
Summary == Quick Help의 제목
Discussion == Quick Help의 내용
이렇게 이해하면 쉽다.

그리고 내용을 입력할때 입력을 하다 줄바꿈을 하고 싶은 경우에는 일반적으로 글을 쓸때는 한줄 바로 밑에 작성을 하지만 마크업에서는 한 줄을 비우고 작성을 해야 원하는 대로 한 줄 밑에 글이 작성이 된다.

/// number는 상수이다.
///
/// number는 
///
/// 항상 0이다.
let number: Int = 0

이 정도만 알아도 퀵헬프 작성에 큰 무리는 없지만 조금 더 표시하기 좋게 만들어 줄 기능에 대해서 알아보고자 한다.

들어가기 전에

직접 테스트를 해보면서 알게 된건데 아무리 공식문서에 올라와있는 기능이라고 해도 직접 해보니 안되는 기능들이 존재 했다.
왜 그런가 History를 가서 확인을 하니 이러했다....

또한 작성하는 오브젝트에 따라서 되는 기능이 있고 안되는 기능이 존재했다.

특정한 어느 기능은 원하는 규칙을 맞추지 않으면 동작하지 않는다.

기호 기능이름: (필수)내용
(선택)내용

• 기호에는 - * + 세 가지중 하나를 써준다.
• 기능 이름에는 위에 적어둔 항목을 써준다.
• 그 옆에 (필수) 적힌 곳에 내용을 써주지 않고 (선택) 에만 내용을 작성하게 된다면 해당 내용은 퀵헬프에 나타나지 않는다.
  코드상에서 바로 옆에 써야 사용가능 이라고 표현

A ~ D

항목: Attention, Author, Authors, Block Comment, Bug, Bulleted Lists, Code Block, Code Voice, Complexity, Copyright, Date

해당 항목들에 대해서는 따로 되거나 안되는 기능이 존재하지 않고 모든 오브젝트에서 동일한 동작을 보였다.

Attention, Author, Authors, Bug, Complexity, Copyright, Date
항목의 경우에는 특별하게 정해진 작성 규칙이 존재한다.(들어가기 전에 참고)

/// Summary 입력부분
///
/// 기능 테스트
/// - Attention: 바로 옆에 써야 사용 가능
///
/// - Author: 바로 옆에 써야 사용 가능
///
/// - Authors: 바로 옆에 써야 사용 가능
///
/// - Bug: 바로 옆에 써야 사용 가능
///
/// ```
/// code는 이렇게 씁니다.
/// ```
///
/// 이건 `CodeVoice`입니다.
///
/// 이건 Non CodeVoice 입니다.
///
/// - 기호 점 표시 가능
///
/// - Complexity: 바로 옆에 써야 사용 가능
///
/// - Copyright: 바로 옆에 써야 사용 가능
///
/// - Date: 바로 옆에 써야 사용 가능
class QuickHelpTest{}

E ~ L

항목: Emphasis(Italics), Escapes, Experiment, Headings, Horizontal Rules, Images, Important, Invariant, Link Reference, Links

Experiment, Important, Invariant
항목의 경우에는 특별하게 정해진 작성 규칙이 존재한다.(들어가기 전에 참고)

Headings, Horizontal Rules, Images
항목의 경우에는 문서상에 있는 방법으로 만들어도 동작하지 않는다.
Headings 의 같이 #, ##, ### 의 경우에는 뒤에 작성한 퀵헬프까지 나타나지 않게 하기에 동작하지 않는 항목의 경우에는 아예 시도도 하지 말것.

Link
항목의 경우에는 문서에 적혀있는 방법 말고 해당 코드에서 사용한 방법으로 작성을 해야 동작이 된다.

/// Summary 입력부분
///
/// 기능 테스트
/// *Italics* | 일반
///
/// \* Escaped 표현, 앞에 * 표시가 붙음
///
/// - Experiment: 바로 옆에 써야 사용 가능
///
/// Heading : ##
///
/// Horizontal Rules :  * * * * *
///
/// ![Xcode icon](http://devimages.apple.com.edgekey.net/assets/elements/icons/128x128/xcode.png "Hover")
/// 이미지 그리는것도 안됨
///
/// - Important: 바로 옆에 써야 사용 가능
///
/// - Invariant: 바로 옆에 써야 사용 가능
///
/// [링크] : https://sean-k.kro.kr/ "Hover Text"
/// 근데 위 방법대로 하면 링크 안 만들어짐
///
/// [링크](https://sean-k.kro.kr)
/// 이렇게 작성해야 링크 생성됨
class QuickHelpTest{}

M ~ R

항목: Note, Numbered Lists, Parameter, Parameters, Postcondition, Precondition, Remark, Returns, Requires

Note, Postcondition, Precondition, Remark, Requires
항목의 경우에는 특별하게 정해진 작성 규칙이 존재한다.(들어가기 전에 참고)

Parameter, Parameters, Returns
항목의 경우에는 Class, Struct, Enum, let, var 를 사용한 오브젝트에는 사용이 불가능하나 func, typealias 를 사용한 오브젝트에서는 사용이 가능하다.

Numbered Lists 항목은 숫자로 리스트를 만들 수 있게 해주며 1,2,3,4,... 와 같이 숫자를 나열식으로 구현을 해도 되고 아니면 코드에 보이는것처럼 1,1,1,... 이런식으로 나열을 해도 같은 root의 depth에 위치한 숫자면 카운트를 자동으로 해준다.

Parameters 항목의 경우에는 또 다른 특별한 작성 규칙이 존재한다.

- Parameters:
	- parameter 이름: parameter 내용
	- parameter 이름: parameter 내용

Parameters 와 Returns 항목은 파라미터와 반환값이 있을 경우에만 사용이 가능한건가 싶어서 Closure 를 사용한 변수를 정의해서 퀵헬프를 작성을 해보았으나 마찬가지로 그냥 일반 변수와 동일하게 취급해 퀵헬프가 작성되지 않았다.
즉 func 과 typalias 가 아니면 아예 동작하지 않는 것을 확인했다.

/// Summary 입력부분
///
/// 기능 테스트
///
/// - Note: 바로 옆에 써야 사용 가능
///
/// 1. Number List
///     1. a
/// 1. Number List
///     1. b
///
/// - Parameters: 특정 오브젝트 사용 불가
///     - A: a
///
/// - Parameter a: 특정 오브젝트 사용 불가
///
/// - Postcondition: 바로 옆에 써야 사용 가능
///
/// - Precondition: 바로 옆에 써야 사용 가능
///
/// - Remark: 바로 옆에 써야 사용 가능
///
/// - Returns: 특정 오브젝트 사용 불가
///
/// - Requires: 바로 옆에 써야 사용 가능
class QuickHelpTest{}

S ~ Z

항목: See Also, Since, Single Line Comment, Strong(Bold), Throws, To Do, Version, Warning

Since, Throws, To Do, Version, Warning
항목의 경우에는 특별하게 정해진 작성 규칙이 존재한다.(들어가기 전에 참고)

SeeAlso 항목의 경우에는 문서내의 작성법으로 시도를 해봤지만 제대로 동작하지 않는것을 확인했다.

/// Summary 입력부분
///
/// 기능 테스트
///
/// SeeAlso: [Link](https://sean-k.kro.kr) 는 안되는데여?
///
/// - Since: 바로 옆에 써야 사용 가능
///
/// **BOLD** | 일반
///
/// - Throws: 바로 옆에 써야 사용 가능
///
/// - ToDo: 바로 옆에 써야 사용 가능
///
/// - Version: 1.0.0
///
/// - Warning: 바로 옆에 써야 사용 가능
class QuickHelpTest{}

마치며

Quick Help 기능은 어떻게 쓰냐에 따라서 코드가 지저분해질 수 도 있고 애초에 필요없는 항목이 될 수도 있다.
하지만 개인적으로 퀵헬프는 유용한 기능이라고 생각해 이렇게 알아보게 되었고 정리를 해봤다.

참고자료

기타

당연 틀린 부분 지적은 감사하나 비난은 정중하게 사양하겠다.