Swift는 설명서 생성을 지원합니까?

Swift는 설명서 생성을 지원합니까?

많은 언어는 생성기를 허용하기 위해 설명서 주석을 지원합니다(예:javadoc또는 doxygen)은 동일한 코드를 구문 분석하여 코드 문서를 생성합니다.

스위프트에는 이와 같은 형식의 문서 주석 기능이 있습니까?

문서 주석은 Xcode에서 기본적으로 지원되며, 빠른 도움말에서 스마트하게 렌더링된 문서를 생성합니다( 기호 클릭 시 팝업 표시 및 빠른 도움말 관리자 모두에서).

기호 문서 주석은 이제 리치 놀이터 주석에서 사용되는 마크다운 구문을 기반으로 하므로 놀이터에서 할 수 있는 많은 작업을 이제 소스 코드 문서에 직접 사용할 수 있습니다.

구문에 대한 자세한 내용은 Markup Formating Reference를 참조하십시오.풍부한 운동장 주석 및 기호 문서화에 대한 구문 간에 몇 가지 불일치가 있습니다. 이는 문서에서 지적한 사항입니다(예: 블록 인용문은 운동장에서만 사용할 수 있습니다).

다음은 현재 기호 문서 주석에 사용되는 구문 요소의 예와 목록입니다.

---

업데이트

Xcode 7 베타 4 ~ 추가됨"- Throws: ...빠른 도움말에 매개 변수 및 반환 설명과 함께 표시되는 최상위 목록 항목입니다.

Xcode 7 베타 1 ~ Swift 2의 구문에 대한 몇 가지 중요한 변경 사항 - 현재 Markdown(놀이터와 동일)에 기반한 문서 주석.

Xcode 6.3(6D570) ~ 들여쓰기 텍스트는 이제 코드 블록으로 포맷되고 이후 들여쓰기는 중첩됩니다.이러한 코드 블록에 빈 줄을 남기는 것은 가능하지 않은 것 같습니다. 그렇게 하려고 하면 텍스트가 문자가 포함된 마지막 줄 끝에 고정됩니다.

Xcode 6.3 베타 ~ 인라인 코드를 백틱을 사용하여 문서 주석에 추가할 수 있습니다.

---

Swift 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:
///
/// ![Swift Logo](/Users/Stuart/Downloads/swift.png "The logo for the Swift programming language")
///
/// - 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의 구문(마크다운 기준)

주석 스타일

둘다요.///와 (으)ㄹ/** */(블록) 스타일 주석은 문서 주석을 생성하는 데 지원됩니다.저는 개인적으로 시각적인 스타일을 선호합니다./** */주석, 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)

이미지:

/// ![Alt Text](http://www.example.com/alt-image.jpg)

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는 Markdown 형식 외에도 빠른 도움말에 눈에 띄게 표시할 다른 마크업 키워드를 인식합니다.이러한 마크업 키워드는 대부분 형식을 취합니다.- <keyword>: 사항:parameter여기에는 콜론 앞에 매개 변수 이름도 포함됩니다. 여기서 키워드 자체는 대문자/소문자 조합으로 작성할 수 있습니다.

기호 섹션 키워드

다음 키워드는 도움말 뷰어의 "설명" 섹션 아래 및 "신고됨" 섹션 위에 중요한 섹션으로 표시됩니다.포함된 경우, 고객의 주문은 아래 표시된 대로 수정되며, 고객이 원하는 순서대로 의견에 포함할 수도 있습니다.

Markup Formating Reference의 Symbol Section Commands 섹션에서 섹션 키워드 및 해당 용도에 대한 전체 문서 목록을 참조하십시오.

/// - parameters:
///   - <#parameter name#>:
///   - <#parameter name#>:
/// - throws:
/// - returns:

또는 다음과 같은 방법으로 각 파라미터를 작성할 수 있습니다.

/// - parameter <#parameter name#>:

기호 설명 필드 키워드

다음 키워드 목록은 도움말 뷰어의 "설명" 섹션 본문에 굵은 제목으로 표시됩니다.이들은 "설명" 섹션의 나머지 부분과 마찬가지로 사용자가 작성한 순서대로 나타납니다.

에리카 사둔의 이 훌륭한 블로그 기사에서 발췌한 전체 목록.또한 마크업 형식 지정 참조의 기호 설명 필드 명령 섹션에서 완전하게 문서화된 키워드 목록과 사용법을 참조하십시오.

귀인:

/// - author:
/// - authors:
/// - copyright:
/// - date:

가용성:

/// - since:
/// - version:

경고:

/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:

개발 상태:

/// - bug:
/// - todo:
/// - experiment:

구현 품질:

/// - complexity:

기능 의미론:

/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:

상호 참조:

/// - seealso:

---

설명서 내보내기

HTML 문서(Apple 자체 문서를 모방하도록 설계됨)는 오픈 소스 명령줄 유틸리티인 Jazzy를 사용하여 인라인 문서에서 생성할 수 있습니다.

$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`

이 NSHipster 기사에서 가져온 콘솔 예

다음은 Xcode 6에서 swift code를 문서화하는 데 사용할 수 있는 몇 가지 사항입니다.벌레가 많고 콜론에 민감하지만 없는 것보다는 낫습니다.

class Foo {

    /// This method does things.
    /// Here are the steps you should follow to use this method
    ///
    /// 1. Prepare your thing
    /// 2. Tell all your friends about the thing.
    /// 3. Call this method to do the thing.
    ///
    /// Here are some bullet points to remember
    ///
    /// * Do it right
    /// * Do it now
    /// * Don't run with scissors (unless it's tuesday)
    ///
    /// :param: name The name of the thing you want to do
    /// :returns: a message telling you we did the thing
    func doThing(name : String) -> String {
        return "Did the \(name) thing";
    }
}

위의 내용은 형식이 지정된 숫자 목록, 글머리 기호, 매개 변수 및 반환 값 문서에서 예상하는 대로 빠른 도움말로 렌더링됩니다.

이 중 어느 것도 문서화되지 않았습니다. 레이더를 기록하여 이들을 도와줍니다.

Xcode 8의 새로운 기능은 다음과 같은 방법을 선택할 수 있습니다.

func foo(bar: Int) -> String { ... }

그런 다음 +를 누르거나 Xcode의 "Editor" 메뉴에서 "Structure" - "Add documentation"을 선택하면 다음 주석 템플릿이 생성됩니다.

/// <#Description#>
///
/// - parameter bar: <#bar description#>
///
/// - returns: <#return value description#>

Swift에는 "///" 댓글 처리가 포함되어 있습니다(아직 전부는 아닐 수도 있음).

다음과 같은 내용을 작성합니다.

/// Hey!
func bof(a: Int) {

}

그런 다음 func 이름과 voila를 옵션으로 클릭합니다 :)

ShakedManChild가 사람들에게 해결책을 제공했다는 것을 확인할 수 있습니다.

설명 아래에 빈 줄이 있는지 확인하십시오!

예. 기본 공통(Obj-C 등가물로 그것을 위한 스니펫을 만들었습니다.

목표-C:

/**
 @brief <#Short description - what it is doing#>

 @discussion <#Description#>

 @param  <#paramName#> <#Description#>.

 @return <#dataType#> <#Description#>.
 */

스위프트

/**
<#Short inline description - what it is doing#>

<#Description#>

:param:  <#paramName#> <#Description#>.

:returns: <#dataType#> <#Description#>.
*/

Xcode Editor에서 -> Structure -> Documentation 추가.

만약 당신이 스위프트만 사용한다면, Jazzy는 볼 가치가 있습니다.

https://github.com/realm/jazzy

Xcode 바이너리에서 흥미로운 것을 발견했습니다.끝이 있는 파일.swiftdoc확실히 문서가 있습니다. 이 파일에는 Swift UIKit / Foundation API용 문서가 포함되어 있기 때문입니다. 안타깝게도 Xcode의 Documentation 뷰어에서 사용하기 위한 독점 파일 형식인 것 같습니다.

Jazzy는 아름다운 애플 스타일의 문서를 생성하는 데 도움을 줄 수 있습니다.다음은 신속한 사용 및 구성 방법에 대한 세부 정보가 포함된 샘플 앱입니다.

https://github.com/SumitKr88/SwiftDocumentationUsingJazzy

아마도 애플 독이나 잘 알려지지 않은 애플의 자체 헤더 독에 눈독을 들이는 것이 좋은 생각일 것입니다.10.9 Mavericks 터미널(headerdoc2html)에서 HeaderDoc 힌트를 여전히 찾을 수 있습니다.

최신 "What's New In Xcode"*(아직도 NDA에 포함되어 있는지 확실하지 않음) *이 링크는 HeaderDoc에 대한 정보가 포함된 Xcode 5.1 버전을 가리킵니다.

Xcode 5.0부터는 Doxygen 및 HeaderDoc 구조화 주석이 지원됩니다.

원천

언급URL : https://stackoverflow.com/questions/24047991/does-swift-have-documentation-generation-support