[ios/tutorial] Xcode 에서 주석을 통해 Documenting 하는 방법

[ios/tutorial] Xcode 에서 주석을 통해 Documenting 하는 방법

http://www.raywenderlich.com/66395/documenting-in-xcode-with-headerdoc-tutorial

-

Documenting 을 header 에 하는 것이 맞을까 implementation 에 하는 것이 맞을까 검색하던 중 좋은 자료를 찾아서 정리해보았다.

-

더 많은 디테일한 정보를 얻고 싶다면, 상단에 링크된 원문을 읽는 것이 추천된다.

-

HeaderDoc 이라는 녀석이 있는데, Xcode5 & iOS7 과 함께 발표된 추가기능이다.

이 녀석은 command line tool 인데, code 에 있는 document 를 HTML 형태로 만들어준다.

( 물론 지원하는 형태로 작성했을 때 이야기이다. )

-

HeaderDoc 에서 지원하는 주석 (comment) 의 형태는 아래와 같이 3가지가 있다.

1.

/// 주석

2.

/**

 *  주석

 */

3.

/*!

 * 주석

 */

싱글 라인은 1번이 주로 사용되고, 멀티 라인은 3번이 주로 사용된다. ( 3번이 애플 doc 스타일 )

그리고 중간에 나오는 * 는 심미적(aesthetic) 인 요인으로 사실 없어도 된다.

-

tag 는 @ 로 시작하는 부연설정해주는 정보이다.

이 tag 는 top-level tag 와 second-level tag 로 나뉘어진다.

top-level tag 는 주석을 만드는 주체에 대한 태그이다. (headers, classes, methods 등등)

그러나 이 녀석들은 Context 를 통해 쉽게 알 수 있고, HeaderDoc 과 같은 Tool 들이 자동으로 생성해주기 때문에,

보통 second-level tag 를 주로 작성한다.

-

second-level tag 는 아래와 같다.

@brief : data type, method 등에 대해 간단히 설명한다.

@abstract : @breif 와 동일

@discussion : @abstract 나 @brief 와 비슷하지만 multiple line 을 허용한다.

@param : parameter 에 대한 이름과 설명이 온다.

@return : return 에 대한 설명을 써준다. ( @result 를 써도 된다. )

@warning : 주의사항을 전달하기 위해 사용한다.

위의 태그들이 general 한 태그들이고, 기타 나머지 태그들은 아래 링크에서 찾을 수 있다.

https://developer.apple.com/library/mac/documentation/DeveloperTools/Conceptual/HeaderDoc/tags/tags.html

-

위와 같은 규칙을 통해 작성된 Comment 는 option + click 을 통해 document 를 popup 의 형태로 볼 수 있다.

-

code snippet ( xcode 우하단 ) 기능을 사용하면 쉽게 문서화 할 수 있다. 

/*!

 * @discussion <#discription#>

 */

위와 같이 작성하면 <#discription#> 파트가 placeholder 로 작동한다.

-

enum 이나 struct 같은 녀석들을 문서화하는 방법은 아래와 같다.

/*!

 * @typedef EnumName

 * @breif 설명

 * @constant (EnumNamePropertyName) (설명) 

 */

만약 이 방법이 귀찮다면, 아래와 같은 방법도 option + click 에 잘 작동한다.

typedef enum{

     /// A cool, old car.

     OldCarTypeModelT,

     /// A sophisticated older car.

     OldCarTypeModelA

} OldCarType;

-

Formatted Code 를 주기 위해서는 @code 를 넣어준다.

ex)

@code [car drive];

-

Project Setting -> Build Settings -> Documentation Comments 의 값을 YES 로 바꾸면,

Compile 할 때 잘못된 documentation 에 대한 warning 을 띄울 수 있다.

-

Special Comment 형태가 있다.

// FIXME : 고쳐야 할 것 명시한다.

// !!! : 주의가 필요한 정보를 넣어준다.

// ??? : 뭔가 의문사항이 있는 경우 넣어준다.

이 정보들은 Xocde 가 인식해서, Jump Bar 에서도 표시를 해준다.

-

개인적으로는 실제 사용할 일이 있을지 모르겠지만, HTML 형태로 Document 문서를 만드는 방법을 정리한다.

1. Project 가 있는 폴더로 이동

2. > headerdoc2html -o [outputFolderPath] [projectFolderPath]

!!! 최근의 headerdoc2html 은 Google Chrome 에서는 잘 안 보이고, Safari 에서 잘 보인다는 report 가 있음.

!!! /// style 주석을 잘 인식 못한다는 report 가 있음. 그래서 가급적 /*! 형태가 추천됨.

-

여러개의 HTML 형태 document 들을 모아 하나의 root HTML 을 또 만들 수도 있다.

document 들이 모여있는 폴더로 이동하여, 아래 명령어를 수행한다.

table 형태로 보여주는 부분을 TOC 이라고 부른다. ( table of contents )

> gatherheaderdoc .

-

3rd party library 로 VVDocumenter-Xcode 라는 플러그 인도 있다.

https://github.com/onevcat/VVDocumenter-Xcode

이 녀석은 알아서 연구하시길..

*, .h, .m, /*!, /**, // !!!, // ???, // fixme, ///, @, @abstract, @brief, @code, @constant, @discussion, @param, @return, @typedef, @wwarning, apple doc style, build settings, code snippet, command line tool, documentation comments, enum, enum 주석, first-level tag, formatted comment, gatherheaderdoc, header, header file, headerdoc, headerdoc2html, HTML, IMPLEMENTATION, jump bar, lint, open source document, option click, placeholder, plug in, popup, project setting, second-level tag, special comment, struct, struct 주석, table, Table of Contents, TAG, Toc, top-level tag, vvdocumenter-xcode, Warning, xcode comment, xcode comment document, xcode documenting, xcode 주석, [ios/tutorial] Xcode 에서 주석을 통해 Documenting 하는 방법, 디테일, 멀티 라인 주석, 심미적, 주석, 컴파일러, 플러그인