[Swift] MarkUp Overview Documentation 작성하기 (설명문서작성)

이 기능의 명칭이 MarkUp Overview라고 하는 것 같은데

함수나 타입에 마우스를 가져다대고

opt(옵션) + (클릭) 을하면 

아래처럼 설명창이 뜨는것을 본적이 있죠?!

이번에는 간단하게 이 문서를 작성하는 방법을 해볼거에요

 

그전에!!!

 

MarkUp??? MarkDown???

둘의 차이가 뭔지 궁금해졌어요

 

MarkUp

마크(Mark)"로 둘러싸인 언어 혹은 "태크(Tag)"로 둘러싸인 언어

문서나 데이터의 구조를 명기하는 언어

라고해요

대표적으로 데이터 표현언어인 HTML과

데이터 교환언어인 XML이 있죠

 

MarkDown

작성한 텍스트를 MarkUp으로 HTML로 변환해주는 언어라고해요

읽고쓰기 쉽게 만들어져있어요

마크를 인식하고 HTML로 변환해줘요

 

예를들어 SNS에서

 #안녕

이라고 친다면 자동으로 해시태그로 인식하기도하고

.md파일에서

*안녕*

하면 볼드체로

안녕

이라고 인식되는 그런 원리에요

 

 

차이를 알아봤으니 다시 돌아와서!!

 

 

우선 문법을 적용시키기위해서는

/// 또는 /** */를 이용해요

구현하면서 어떻게 적용되나 보도록해볼게요

 

 

 

 

함수의 매개변수에 대한 설명을 주고싶어요

그러면

parameter 혹은 parameters를 쓰면되요

대소문자도 구분상관없어요

 

// MARK: 방법1

/// - parameter name: 이름
/// - parameter age: 나이
func myFunction(name: String, age: Int) {}

// MARK: 방법2

/// - parameters:
///     - name: 이름
///     - age: 나이
func myFunction(name: String, age: Int) {}

// MARK: 방법3

/**
 - parameters:
    - name: 이름
    - age: 나이
*/
func myFunction(name: String, age: Int) {}

 

우선 ///를 쓰냐 /** */는 편한대로 사용하시면 되구요

parameter는 어떻게 구현하든 방법은 여러가지에요

매개변수명과 맞지않는다면 동작하지않으니 주의하구요

이쁘게 잘나오네요 ㅎㅎ

 

 

문법에 해당하는 단어만 알면 어려울게 없어요!!

 

우선 마크다운에도 있는 문법이 적용되는것도 있어요

 

*기울기* -> 기울기체

**볼드** -> 볼드체

`텍스트` -> 텍스트체(?) 약간 똑바르게생긴 문자가나와요

* 목차 -> •목차

 

~~~

코드작성

~~~

-> 에디터

 

개행을 하려면 엔터2번을 해야하구요!

 

[나타날단어](링크) 하면 링크가걸리구요

ex) [블로그링크](https://nsios.tistory.com)

 

parameter: 함수 매개변수설명

Throws: 에러를 설명

Returns: 리턴값을 설명

Important: 중요한 설명

Note: 노트

Version: 버전기재

 

등등 

이것 외에도 많은 기능들로 Overview를 통해서 설명 할 수 있어요

자세한건 애플 문서를 참고하시구요!!

developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/index.html#//apple_ref/doc/uid/TP40016497-CH2-SW1

 

 

구현코드와 결과물 보여드릴게요!!

 

/**
 [블로그링크](https://nsios.tistory.com)
 
 일반 텍스트
 
 ` 텍스트체 `
 
 *기울기체*

 **볼드체**

 * 목차1
 * 목차2
 
 ~~~
 // 코드를 작성할 수 있어요
 let name: String = "남수"
 let age: Int = 26
 myFunction(name: name, age: age)
 ~~~
 
 - Parameters:
    - name: 이름은 `name`
    - age: 나이

 - Throws: 에러를 던질거야
 
 - Returns: 어떤게 나올까 궁금하지?
 
 - important: 중요한경우
 
 - note: 노트노트
 
 - version: 1.0.0
 
*/
func myFunction(name: String, age: Int) {}

 

일반 문장을 치면 제일 위에 한줄만 Summary로 가고

나머지 문장은 Discussion으로 나타나요