Komentar dokumentasi didukung secara asli di Xcode, menghasilkan dokumentasi yang diterjemahkan dengan cerdas dalam Bantuan Cepat (keduanya dalam ⌥sembulan ketika -klik simbol, dan di Inspektur Bantuan Cepat ⌥⌘2).
Komentar dokumentasi simbol sekarang didasarkan pada sintaks Markdown yang sama yang digunakan oleh komentar taman bermain yang kaya, sehingga banyak hal yang dapat Anda lakukan di taman bermain sekarang dapat digunakan secara langsung dalam dokumentasi kode sumber.
Untuk detail lengkap sintaks, lihat Referensi Pemformatan Markup . Perhatikan bahwa ada beberapa perbedaan antara sintaksis untuk komentar taman bermain kaya & dokumentasi simbol; ini ditunjukkan dalam dokumen (mis. kutipan blok hanya dapat digunakan di taman bermain).
Di bawah ini adalah contoh dan daftar elemen sintaks yang saat ini berfungsi untuk komentar dokumentasi simbol.
Pembaruan
Xcode 7 beta 4 ~ Ditambahkan " - Throws: ..." sebagai item daftar tingkat atas yang muncul di samping parameter dan mengembalikan deskripsi dalam Bantuan Cepat.
Xcode 7 beta 1 ~ Beberapa perubahan signifikan pada sintaksis dengan Swift 2 - komentar dokumentasi sekarang berdasarkan Markdown (sama seperti taman bermain).
Xcode 6.3 (6D570) ~ Teks indentasi sekarang diformat sebagai blok kode, dengan lekukan berikutnya yang bersarang. Tampaknya tidak mungkin untuk meninggalkan baris kosong di blok kode seperti itu - mencoba melakukannya menghasilkan teks yang ditempelkan di akhir baris terakhir dengan karakter apa pun di dalamnya.
Xcode 6.3 beta ~ Kode inline sekarang dapat ditambahkan ke komentar dokumentasi menggunakan backticks.
Contoh untuk 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:
///
/// 
///
/// - 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."
}
Sintaks untuk Swift 2 (berdasarkan penurunan harga )
Gaya Komentar
Kedua ///(inline) dan /** */komentar (blok) gaya yang didukung untuk memproduksi komentar dokumentasi. Sementara saya pribadi lebih suka gaya visual /** */komentar, lekukan otomatis Xcode dapat merusak format untuk gaya komentar ini saat menyalin / menempel karena menghilangkan spasi putih terkemuka. Sebagai contoh:
/**
See sample usage:
let x = method(blah)
*/
Saat menempel, indentasi blok kode dihapus dan tidak lagi dirender sebagai kode:
/**
See sample usage:
let x = method(blah)
*/
Untuk alasan ini, saya biasanya menggunakan ///, dan akan menggunakannya untuk sisa contoh dalam jawaban ini.
Elemen Blok
Tajuk:
/// # My Heading
atau
/// My Heading
/// ==========
Subpos:
/// ## My Subheading
atau
/// My Subheading
/// -------------
Aturan horisontal:
/// ---
Daftar tidak berurutan (berpoin):
/// - An item
/// - Another item
Anda juga dapat menggunakan +atau *untuk daftar tidak berurutan, hanya saja harus konsisten.
Daftar yang dipesan (bernomor):
/// 1. Item 1
/// 2. Item 2
/// 3. Item 3
Blok kode:
/// for item in array {
/// print(item)
/// }
Lekukan setidaknya empat ruang diperlukan.
Elemen Sebaris
Penekanan (miring):
/// Add like *this*, or like _this_.
Kuat (berani):
/// You can **really** make text __strong__.
Perhatikan bahwa Anda tidak dapat mencampur tanda bintang ( *) dan garis bawah ( _) pada elemen yang sama.
Kode sebaris:
/// Call `exampleMethod(_:)` to demonstrate inline code.
Tautan:
/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)
Gambar-gambar:
/// 
URL dapat berupa URL web (menggunakan "http: //") atau URL path file absolut (Saya sepertinya tidak bisa mendapatkan path file relatif untuk bekerja).
URL untuk tautan dan gambar juga dapat dipisahkan dari elemen sebaris untuk menjaga semua URL di satu tempat yang dapat dikelola:
/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg
Kata kunci
Selain pemformatan Markdown, Xcode mengenali kata kunci markup lainnya untuk ditampilkan secara jelas di Bantuan Cepat. Kata kunci markup ini sebagian besar mengambil format - <keyword>:(pengecualiannya adalahparameter , yang juga menyertakan nama parameter sebelum titik dua), di mana kata kunci itu sendiri dapat ditulis dengan kombinasi karakter huruf besar / kecil.
Kata kunci Bagian Simbol
Kata kunci berikut ditampilkan sebagai bagian yang menonjol di penampil bantuan, di bawah bagian "Deskripsi", dan di atas bagian "Dinyatakan dalam". Ketika disertakan, pesanan mereka diperbaiki seperti yang ditampilkan di bawah ini meskipun Anda dapat memasukkannya dalam urutan apa pun yang Anda suka dalam komentar Anda.
Lihat daftar kata kunci bagian yang sepenuhnya terdokumentasi dan kegunaannya di bagian Perintah Bagian Simbol dari Referensi Pemformatan Markup .
/// - parameters:
/// - <#parameter name#>:
/// - <#parameter name#>:
/// - throws:
/// - returns:
Atau, Anda dapat menulis setiap parameter dengan cara ini:
/// - parameter <#parameter name#>:
Simbol Deskripsi Kata kunci bidang
Daftar kata kunci berikut ditampilkan sebagai judul tebal di badan bagian "Deskripsi" pada penampil bantuan. Mereka akan muncul dalam urutan apa pun yang Anda tuliskan, seperti bagian "Deskripsi" lainnya.
Daftar lengkap diparafrasekan dari artikel blog yang sangat baik ini oleh Erica Sadun. Juga lihat daftar kata kunci yang sepenuhnya didokumentasikan dan kegunaan yang dimaksudkan di bagian Perintah Keterangan Simbol dari Referensi Pemformatan Markup .
Atribusi:
/// - author:
/// - authors:
/// - copyright:
/// - date:
Ketersediaan:
/// - since:
/// - version:
Peringatan:
/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:
Negara pembangunan:
/// - bug:
/// - todo:
/// - experiment:
Kualitas Penerapan:
/// - complexity:
Semantik Fungsional:
/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:
Referensi silang:
/// - seealso:
Mengekspor Dokumentasi
Dokumentasi HTML (dirancang untuk meniru dokumentasi Apple sendiri) dapat dihasilkan dari dokumentasi inline menggunakan Jazzy , utilitas baris perintah sumber terbuka.
$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`
Contoh konsol yang diambil dari artikel NSHipster ini
