문서 주석은 Xcode에서 기본적으로 지원되며 빠른 도움말 ( ⌥심볼을 클릭 할 때 팝업 및 빠른 도움말 검사기 ⌥⌘2) 에서 스마트하게 렌더링 된 문서를 생성 합니다.
기호 문서 주석은 이제 풍부한 놀이터 주석에서 사용 된 것과 동일한 Markdown 구문을 기반으로 하므로 놀이터에서 수행 할 수있는 많은 작업을 이제 소스 코드 문서에서 직접 사용할 수 있습니다.
구문에 대한 자세한 내용은 마크 업 서식 참조를 참조하십시오 . 풍부한 운동장 의견과 기호 문서에 대한 구문에는 약간의 차이가 있습니다. 이것들은 문서에서 지적됩니다 (예 : 블록 따옴표는 놀이터에서만 사용할 수 있습니다).
아래는 기호 문서 주석에 현재 작동하는 구문 요소의 예와 목록입니다.
업데이트
Xcode 7 베타 4 ~ " - Throws: ..."를 최상위 목록 항목으로 추가 하여 매개 변수와 함께 표시되며 빠른 도움말의 설명을 반환합니다.
Xcode 7 베타 1 ~ Swift 2의 구문에 대한 몇 가지 중요한 변경 사항-이제 마크 다운 (놀이터와 동일)을 기반으로하는 문서 주석.
Xcode 6.3 (6D570) ~ 들여 쓰기 된 텍스트가 이제 코드 블록으로 포맷되며, 이후 들여 쓰기가 중첩됩니다. 이러한 코드 블록에 빈 줄을 남겨 두는 것은 불가능한 것으로 보입니다. 그렇게하면 텍스트가 마지막 줄의 끝에 문자가 붙습니다.
Xcode 6.3 베타 ~ 인라인 코드를 백틱을 사용하여 문서 주석에 추가 할 수 있습니다.
스위프트 2의 예
/// Text like this appears in "Description".
///
/// Leave a blank line to separate further text into paragraphs.
///
/// You can use bulleted lists (use `-`, `+` or `*`):
///
/// - Text can be _emphasised_
/// - Or **strong**
///
/// Or numbered lists:
///
/// 7. The numbers you use make no difference
/// 0. The list will still be ordered, starting from 1
/// 5. But be sensible and just use 1, 2, 3 etc…
///
/// ---
///
/// More Stuff
/// ==========
///
/// Code
/// ----
///
/// Use backticks for inline `code()`. Indentations of 4 spaces or more will create a code block, handy for example usage:
///
/// // Create an integer, and do nothing with it
/// let myInt = 42
/// doNothing(myInt)
///
/// // Also notice that code blocks scroll horizontally instead of wrapping.
///
/// Links & Images
/// --------------
///
/// Include [links](https://en.wikipedia.org/wiki/Hyperlink), and even images:
///
/// 
///
/// - note: That "Note:" is written in bold.
/// - requires: A basic understanding of Markdown.
/// - seealso: `Error`, for a description of the errors that can be thrown.
///
/// - parameters:
/// - int: A pointless `Int` parameter.
/// - bool: This `Bool` isn't used, but its default value is `false` anyway…
/// - throws: A `BadLuck` error, if you're unlucky.
/// - returns: Nothing useful.
func doNothing(int: Int, bool: Bool = false) throws -> String {
if unlucky { throw Error.BadLuck }
return "Totally contrived."
}
Swift 2의 구문 ( Markdown 기반 )
댓글 스타일
둘 다 ///(인라인)와 /** */(블록) 스타일의 코멘트 문서 주석 생산 지원됩니다. 개인적으로 시각적 인 /** */주석 스타일을 선호하지만 Xcode의 자동 들여 쓰기는 앞의 공백을 제거하여 복사 / 붙여 넣기시이 주석 스타일의 서식을 손상시킬 수 있습니다. 예를 들면 다음과 같습니다.
/**
See sample usage:
let x = method(blah)
*/
붙여 넣을 때 코드 블록 들여 쓰기가 제거되고 더 이상 코드로 렌더링되지 않습니다.
/**
See sample usage:
let x = method(blah)
*/
이러한 이유로 나는 일반적으로을 사용 ///하고이 답변의 나머지 예제에 사용합니다.
블록 요소
표제:
/// # My Heading
또는
/// My Heading
/// ==========
소제목:
/// ## My Subheading
또는
/// My Subheading
/// -------------
수평 규칙 :
/// ---
순서가없는 (글 머리 기호) 목록 :
/// - An item
/// - Another item
+또는 *정렬되지 않은 목록을 사용 하거나 일관성을 유지해야합니다.
순서 (번호) 목록 :
/// 1. Item 1
/// 2. Item 2
/// 3. Item 3
코드 블록 :
/// for item in array {
/// print(item)
/// }
최소 4 개의 공백 들여 쓰기가 필요합니다.
인라인 요소
강조 (이탈리아) :
/// Add like *this*, or like _this_.
강력 (굵게) :
/// You can **really** make text __strong__.
동일한 요소에 별표 ( *)와 밑줄 ( _)을 혼합 할 수 없습니다 .
인라인 코드 :
/// Call `exampleMethod(_:)` to demonstrate inline code.
연결:
/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)
이미지 :
/// 
URL은 웹 URL ( "http : //"사용) 또는 절대 파일 경로 URL 일 수 있습니다 (상대적인 파일 경로가 작동하지 않는 것 같습니다).
링크와 이미지의 URL을 인라인 요소와 분리하여 모든 URL을 관리 가능한 한 곳에 보관할 수 있습니다.
/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg
키워드
마크 다운 형식 외에도 Xcode는 다른 마크 업 키워드를 인식하여 빠른 도움말에 눈에 띄게 표시됩니다. 이 마크 업 키워드는 대부분 형식을 취합니다 - <keyword>:(예외는 parameter콜론 앞의 매개 변수 이름도 포함). 키워드 자체는 대문자 / 소문자를 조합하여 작성할 수 있습니다.
심볼 섹션 키워드
다음 키워드는 도움말 뷰어, "설명"섹션 및 "선언"섹션 위에 눈에 잘 띄는 섹션으로 표시됩니다. 포함 된 경우 주석에 원하는 순서대로 포함 할 수 있지만 순서는 아래 표시된대로 고정됩니다.
마크 업 형식화 참조 의 기호 섹션 명령 섹션 에서 섹션 키워드 및 용도에 대한 전체 문서를 참조하십시오 .
/// - parameters:
/// - <#parameter name#>:
/// - <#parameter name#>:
/// - throws:
/// - returns:
또는 다음과 같이 각 매개 변수를 작성할 수 있습니다.
/// - parameter <#parameter name#>:
기호 설명 필드 키워드
다음 키워드 목록은 도움말 뷰어의 "설명"섹션 본문에 굵게 표시됩니다 . "설명"섹션의 나머지 부분과 같이 작성 순서에 관계없이 나타납니다.
전체 목록 은 Erica Sadun 의이 훌륭한 블로그 기사 에서 해석되었습니다. 또한 마크 업 형식화 참조 의 기호 설명 필드 명령 섹션 에서 키워드 및 해당 용도의 전체 목록을 참조하십시오 .
기여 :
/// - author:
/// - authors:
/// - copyright:
/// - date:
유효성:
/// - since:
/// - version:
훈계 :
/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:
개발 상태 :
/// - bug:
/// - todo:
/// - experiment:
구현 품질 :
/// - complexity:
기능적 의미론 :
/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:
상호 참조:
/// - seealso:
문서 내보내기
오픈 소스 명령 줄 유틸리티 인 Jazzy를 사용하여 인라인 문서에서 HTML 문서 (Apple 자체 문서를 모방하도록 설계됨)를 생성 할 수 있습니다 .
$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`
이 NSHipster 기사 에서 가져온 콘솔 예제
