質問

多くの言語がサポート ドキュメントコメント を使用して、ジェネレータ（例えば javadoc または ドキシジェン ) を使って、同じコードを解析してコードドキュメントを生成することができます。

Swiftにはこのような型文書コメント機能はないのでしょうか？

どのように解決するのですか？

ドキュメントコメントは、Xcodeでネイティブにサポートされており、クイックヘルプでスマートにレンダリングされたドキュメントを生成します（[1]のポップオーバーの両方）。 ⌥ -シンボルをクリックすると表示されるクイックヘルプインスペクタと ⌥⌘2 ).

シンボル・ドキュメントのコメントは、現在、同じ マークダウン構文 リッチプレイグラウンドのコメントで使用されているため、プレイグラウンドでできることの多くが、ソースコードのドキュメントで直接使用できるようになりました。

構文の詳細については マークアップフォーマットリファレンス . リッチプレイグラウンドコメントとシンボルドキュメントの構文には、いくつかの相違があることに注意してください。

以下は、シンボル・ドキュメント・コメントで現在機能している構文要素の例とリストです。

---

更新情報

Xcode 7 beta 4 ~. "を追加しました。 - Throws: ... クイックヘルプのパラメータや戻り値の説明と一緒に表示されるトップレベルのリスト項目として "を追加しました。

Xcode 7 ベータ1 Swift 2の構文へのいくつかの重要な変更 - ドキュメントコメントは現在Markdownに基づいています（playgroundsと同じ）。

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は、WebのURL（"http://"を使用）または絶対ファイルパスURL（相対ファイルパスはうまくいかないようです）のいずれかを使用します。

また、リンクや画像のURLをインライン要素から分離することで、すべてのURLを一箇所にまとめて管理することができます。

/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg

キーワード

Markdownフォーマットに加え、Xcodeは他のマークアップキーワードを認識し、クイックヘルプで目立つように表示します。これらのマークアップキーワードは主に以下のフォーマットをとります - <keyword>: (例外は parameter キーワードは、大文字と小文字の組み合わせで書くことができます。

シンボルセクションのキーワード

以下のキーワードは、ヘルプビューアの目立つセクションとして、"Description"セクションの下、"Declared In"セクションの上に表示されます。このキーワードが含まれている場合、その順番は以下のように固定されますが、コメントの中で好きな順番で含めることができます。

セクションキーワードとその使用法については マークアップフォーマットリファレンス』「シンボルセクションコマンド」セクション .

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

また、各パラメータをこのように記述することもできます。

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

シンボル説明 フィールドキーワード

として、以下のキーワード一覧が表示されます。 太字見出し ヘルプビューアのquot;Description"セクションの本文にあります。これらは、他のセクションと同様に、どのような順番で書かれても表示されます。

全リストは以下のサイトから引用しています。 この素晴らしいブログの記事 Erica Sadunによるものです。また、キーワードとその用途を完全に文書化したリストは マークアップフォーマットリファレンス」の「記号の説明フィールドコマンド」の項を参照。 .

アトリビュート

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

可用性。

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

諭吉さん

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

開発状態です。

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

インプリメンテーション・クオリティー

/// - complexity:

ファンクショナル・セマンティクス

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

クロスリファレンスです。

/// - seealso:

---

 ドキュメントのエクスポート

HTML ドキュメント（Apple 独自のドキュメントを模倣したデザイン）は、インラインのドキュメントから次のようにして生成できます。 ジャジー は、オープンソースのコマンドラインユーティリティです。

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

コンソールの例 このNSHipsterの記事