XcodeでSwift1.xのコードを変換すると、文書コメント（関数やメソッドなどのコメント）も一緒にコンバートされるので気づいた人もいると思いますが、文書コメントの記法が変わりました。
以前はパラメータやリターンコード、あとはリスト表記など簡単なものしかありませんでしたが、Swift 2になりmarkdown記法に似た感じに変更され、コメントコマンドもかなり増えてます。
Playgoundのドキュメントレンダリング用とシンボルドキュメントで記法が若干違うのですが、今回シンボルドキュメントの方を中心に書いてみました。
ここにドキュメントがあります。
prayground
//: 1行のコメント
/*:
複数行のコメント
*/
シンボルドキュメント
/// 1行のコメント
/**
複数行のコメント
*/
Line formmating
行を装飾するフォーマットで7種類のコマンドが用意されています。
- Block Quotes
文字通りブロック単位でコメントを分ける。複数行を1つのブロックにするときは、各行の後ろに空白2つ必要。ブロックは前後にラインが引かれる。Playgroundのみ。
BlockQuotes
/*:
>ブロック1行目
>ブロック2行目
*/
- Bulleted ListsとNumbered Lists
リスト表現をする。「+」「-」を先頭に指定。数字+「.」で番号のリストを表現。
BulletedLists/NumberedLists
/**
- リスト表記
- 2段目
1. 数字のリスト
*/
表示例
- Code Blocks
プログラムコードのブロックを指定できる。関数の使用例など書くのに便利。
「````」でブロック指定。(以下のコードでは````となっているが、実際には「\」は削除します)
※ @gnueさんから指摘があったのですが、実際には「`」は3個で機能します。ちなみに公式ドキュメントでは4個となっていますので、ここでは4個で記載しておきます。
CodeBlocks
/**
以下コード
\````
func hoge() {
print("sample")
}
\````
*/
表示例
- Headings 「#」で見出しを表現します。
Headings
/**
# 見出し1
## 見出し2
### 見出し3
*/
表示例
- Horizontal Rules 「----」で区切り線が引けます。
HorizontalRules
/**
----
↑区切り線
*/
表示例
- Link Reference 「[文字列]:URL ホバー文字列」でリンクを定義し、「[ 文字列 ]」でリンクを埋め込める。 （[Developer ...になってるが実際には先頭の「\」は削除します）
HorizontalRules
/**
\[Developer Program]: http://developer.apple.com/ "DevCenter"
Developer:[Developer Program]
*/
表示例
ちょっと宣伝
コメントの特殊な記述方法ってあまり書籍に載っていないんですよね。
でも「Swift 2 標準ガイドブック」にはきちんと載ってます。
細かい部分まで知りたい人は、買ってください〜。
2015年11月24日まで特別価格になっています。