Skip to content

sweepty

Markup으로 Quick Help 만들기

— 1 min read

CocoaPods을 만지고 있는 중인데 갑자기 option + click 을 하면 나오는 이것은 어떻게 하는 것인지 궁금해졌다.

quickHelp1

사실 명칭도 잘 몰랐는데 지금 찾아보니 ==Quick Help==라고 한다. command + click 해도 나온다.

아무래도 SDK이다보니 개발자들을 위해서 설명을 친절하게 해주어야 좋을 거 같아서 꼭 해야겠다는 생각이 들었다.

할거면 제대로 만들어보고 싶기도 하고 새로운 것을 시도해보고 싶어서ㅎㅎ 그리고 회사꺼니까… 제대로 해야해 (중요)

다시 보니까 Fundamentals, 즉 기초적인 건데 지금까지 해본 적이 없다.. 지금이라도 알아서 다행이다ㅠㅠ

인턴하면서 내가 기초적인 부분이 부족하다는 걸 다시 알게 되었고 반성하면서 배우려고 하는 중...

References

API Design Guidelines - Fundamentals

Markup Formatting Reference

까칠코더님의 한글 번역글

Markup

Markup이 뭔가요?

Markup for Swift symbols is used for Quick Help and for the description shown in symbol completion.

Quick Help를 작성하기 위해 사용하는 것이 바로 Markup이다.

예시

API Design Guideline의 example.

1/// Writes the textual representation of each    ← Summary
2/// element of `items` to the standard output.
3///                                              ← Blank line
4/// The textual representation for each item `x` ← Additional discussion
5/// is generated by the expression `String(x)`.
6///
7/// - Parameter separator: text to be printed    ⎫
8///   between items.                             ⎟
9/// - Parameter terminator: text to be printed   ⎬ Parameters section
10///   at the end.                                ⎟
11///                                              ⎭
12/// - Note: To print without a trailing          ⎫
13///   newline, pass `terminator: ""`             ⎟
14///                                              ⎬ Symbol commands
15/// - SeeAlso: `CustomDebugStringConvertible`,   ⎟
16///   `CustomStringConvertible`, `debugPrint`.   ⎭
17public func print(
18  _ items: Any..., separator: String = " ", terminator: String = "\n")

간단하다! Quick Help를 만들고 싶은 function 상단에 Markup을 작성하면 된다.

바로 이렇게 나옴!! 엥 근데 SeeAlso는 왜 안보이지?? quickHelp2

``는 Code Voice 라는 것인데 Code Voice용 폰트로 렌더링을 해준다고 한다. 폰트가 다르게 보이는 것을 알 수 있을 것임.

아래는 내가 만들어본 Markup

1/// Convert ICX or gLoop value to loop.
2///
3/// - Parameters
4///     - value: 변환하려는 value 값.
5///     - unit: value의 단위 값. default = .icx
6/// - Returns: loop로 변환된 value 값.
7/// 
8public static func convertToLoop(value: BigUInt, unit: Unit = .icx) -> BigUInt {
9
10}

개발자들의 최대 난제인 커밋 메세지 작성하기, 변수명 함수명 짓기에 Quick Help 작성하기도 추가될 것 같다… 아직 저거 다 넘 어려워요..

Formatting Quick Help 에 따르면 큰 부분으로 나누면 다음과 같다.

  • Description section
  • Parameters section
  • Throws section
  • Returns section

아마도 내가 사용할 것은 이 정도가 될듯.

  • Description section

    • Summary
    • Additional Discussion

  • Parameter section

    • Parameters

  • Return

  • Throws

더 많은 Markup delimiters 는 여기에 있다.

우선 나는 아주 기본적인 것만 작성하려고 한다. Note나 SeeAlso 이런건 적을 것도 없을 것 같고 아직 벅찰 거 같음.

몇번 작성해보고 알게 된 주의사항

시범적으로 적용해보다가 헷갈리는 부분이 있어서 정리.

  1. indentation을 지켜야 한다.

잘못된 예

1/// Convert ICX or gLoop to loop.
2/// 
3/// - Parameters
4///     - value: 바꾸려는 value값
5///     - unit: value의 단위. default = icx
6/// - Returns: loop
7/// 
8public static func convertToLoop(value: BigUInt, unit: Unit = .icx) -> BigUInt {
9}

처음에 잘 몰라서 이렇게 했는데 discussion 항목에 parameters가 불렛 형식으로 나와서 당황했다.

꼭 indentation을 지켜야하는 듯.

올바른 예

1/// Convert ICX or gLoop to loop.
2///
3/// - Parameters:
4///   - value: 바꾸려는 value값
5///   - unit: value의 단위. default = icx
6/// - Returns: loop
7public static func convertToLoop(value: BigUInt, unit: Unit = .icx) -> BigUInt {
8}

Space 3칸이다.

  1. 단락 구분은 blank line으로 한다.
1/// Convert ICX or gLoop to loop. <- Summary
2///                               <- Blank line
3/// - Parameters:
4///   - value: 바꾸려는 value값
5///   - unit: value의 단위. default = icx
6/// - Returns: loop
7public static func convertToLoop(value: BigUInt, unit: Unit = .icx) -> BigUInt {
8}

혹시 틀린 점이 있으면 댓글로 알려주시면 감사하겠습니다.