Banyak bahasa mendukung komentar dokumentasi untuk memungkinkan generator (seperti javadocatau doxygen ) menghasilkan dokumentasi kode dengan menguraikan kode yang sama.

Apakah Swift memiliki fitur komentar jenis dokumentasi seperti ini?

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:
///
/// ![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."
}

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:

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

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

Berikut adalah beberapa hal yang berfungsi untuk mendokumentasikan kode cepat di Xcode 6. Sangat bermasalah dan sensitif terhadap titik dua, tetapi lebih baik daripada tidak sama sekali:

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";
    }
}

Di atas diberikan dalam Bantuan Cepat seperti yang Anda harapkan dengan daftar angka yang diformat, poin-poin, parameter dan dokumentasi nilai pengembalian.

Tak satu pun dari ini didokumentasikan - mengajukan Radar untuk membantu mereka.

Baru di Xcode 8 , Anda dapat memilih metode seperti ini

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

Kemudian tekan command+ option+/ atau pilih "Struktur" - "Tambahkan dokumentasi" dari menu "Editor" Xcode, dan itu akan menghasilkan templat komentar berikut untuk Anda:

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

Swift termasuk penanganan komentar "///" (walaupun mungkin belum semuanya).

Tulis sesuatu seperti:

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

}

Kemudian klik opsi pada nama func dan voila :)

Saya dapat mengonfirmasi bahwa ShakenManChild telah menyediakan solusi peopr

Pastikan saja, Anda memiliki baris kosong di bawah deskripsi!

Iya. Dasar umum (saya membuat cuplikan untuknya dengan setara Obj-C)

Tujuan-C:

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

 @discussion <#Description#>

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

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

Cepat

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

<#Description#>

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

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

Jika Anda hanya menggunakan Swift maka Jazzy layak untuk dilihat.

https://github.com/realm/jazzy

Saya telah menemukan sesuatu yang menarik, menggali dalam biner Xcode. File dengan akhiran .swiftdoc. Ini pasti memiliki dokumen, karena file-file ini mengandung dokumen untuk Swift UIKit / Foundation API, sayangnya itu tampaknya merupakan format file berpemilik, untuk digunakan dalam penampil Dokumentasi dalam Xcode.

Di Editor Xcode -> Struktur -> Tambahkan Dokumentasi.

Jazzy dapat membantu menghasilkan dokumentasi bergaya apel yang indah. Berikut adalah contoh aplikasi dengan detail tentang cara menggunakan dan mengonfigurasi dengan cepat.

https://github.com/SumitKr88/SwiftDocumentationUsingJazzy

Mungkin itu ide yang baik untuk memiliki mata pada AppleDoc atau Apple sendiri HeaderDoc yang tidak diakui sangat banyak. Saya masih dapat menemukan beberapa petunjuk HeaderDoc di terminal 10.9 Mavericks (headerdoc2html)

Saya sarankan untuk membaca " What's New In Xcode " terbaru (* tidak yakin apakah masih di bawah NDA) * Tautan menunjuk ke versi Xcode 5.1 yang berisi info tentang HeaderDoc juga.

Pada Xcode 5.0, komentar terstruktur Doxygen dan HeaderDoc didukung.

Sumber