Dokümantasyon yorumları yerel olarak Xcode'da desteklenir ve Hızlı Yardım'da (hem ⌥sembolleri tıklarken popoverde hem de Hızlı Yardım Denetçisi'nde ⌥⌘2) akıllıca hazırlanmış belgeler üretir .
Sembol dokümantasyon yorumları artık zengin oyun alanı yorumları tarafından kullanılan Markdown sözdizimine dayanmaktadır , bu nedenle oyun alanlarında yapabileceklerinizin çoğu artık doğrudan kaynak kodu dokümantasyonunda kullanılabilir.
Sözdiziminin tüm ayrıntıları için bkz. İşaretleme Biçimlendirme Başvurusu . Zengin oyun alanı yorumları ve sembol belgeleri için sözdizimi arasında bazı tutarsızlıklar olduğunu unutmayın; bunlar belgede belirtilmiştir (örn. blok alıntılar sadece oyun alanlarında kullanılabilir).
Aşağıda, şu anda sembol dokümantasyon yorumları için çalışan sözdizimi öğelerinin bir örneği ve listesi bulunmaktadır.
Güncellemeler
Xcode 7 beta 4 ~- Throws: ... Hızlı Yardım'da parametrelerin ve dönüş açıklamalarının yanında görünen üst düzey liste öğesi olarak " " eklendi .
Xcode 7 beta 1 ~ Swift 2 ile sözdizimindeki bazı önemli değişiklikler - şimdi Markdown'a dayanan (oyun alanlarıyla aynı) dokümantasyon yorumları.
Xcode 6.3 (6D570) ~ Girintili metin artık kod blokları olarak biçimlendirildi ve sonraki girintiler yuvalandı. Böyle bir kod bloğunda boş bir satır bırakmak mümkün görünmemektedir - bunu yapmaya çalışmak, metnin içinde herhangi bir karakterle son satırın sonuna yapışmasını sağlar.
Xcode 6.3 beta ~ Satıriçi kod artık backticks kullanılarak dokümantasyon yorumlarına eklenebilir.
Swift 2 örneği
/// 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."
}
Swift 2 için Sözdizimi ( Markdown'a dayalı )
Yorum Stili
Doküman yorumları oluşturmak için hem ///(satır içi) hem de /** */(blok) stil yorumlar desteklenir. Şahsen /** */yorumların görsel stilini tercih ederken , Xcode'un otomatik girintisi, önde gelen boşluğu kaldırırken kopyalama / yapıştırma sırasında bu yorum stili için biçimlendirmeyi bozabilir. Örneğin:
/**
See sample usage:
let x = method(blah)
*/
Yapıştırırken, kod bloğu girintisi kaldırılır ve artık kod olarak görüntülenmez:
/**
See sample usage:
let x = method(blah)
*/
Bu nedenle, genellikle ///bu cevaptaki diğer örnekler için kullanıyorum ve kullanacağım.
Blok Elemanları
Başlık:
/// # My Heading
veya
/// My Heading
/// ==========
Alt pozisyonuna:
/// ## My Subheading
veya
/// My Subheading
/// -------------
Yatay kural:
/// ---
Sırasız (madde işaretli) listeler:
/// - An item
/// - Another item
Ayrıca +veya *sırasız listeler için kullanabilirsiniz , tutarlı olması gerekir.
Sıralı (numaralı) listeler:
/// 1. Item 1
/// 2. Item 2
/// 3. Item 3
Kod blokları:
/// for item in array {
/// print(item)
/// }
En az dört boşluk girintisi gerekir.
Satır İçi Öğeler
Vurgu (italik):
/// Add like *this*, or like _this_.
Güçlü (kalın):
/// You can **really** make text __strong__.
Aynı öğede yıldız ( *) ve alt çizgi ( _) karıştıramayacağınızı unutmayın .
Satır içi kod:
/// Call `exampleMethod(_:)` to demonstrate inline code.
Bağlantılar:
/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)
Görüntüler:
/// 
URL, bir web URL'si ("http: //" kullanarak) veya mutlak dosya yolu URL'si olabilir (göreli dosya yollarının çalışmasını sağlayamıyorum).
Bağlantıların ve resimlerin URL'leri, tüm URL'leri tek bir yönetilebilir yerde tutmak için satır içi öğeden ayrılabilir:
/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg
Anahtar kelimeler
Markdown biçimlendirmesine ek olarak, Xcode, diğer Yardım biçimlendirme anahtar kelimelerinin Hızlı Yardım'da belirgin bir şekilde görüntülenmesini tanır. Bu biçimlendirme anahtar kelimeleri çoğunlukla , iki nokta üst üste / küçük harf karakterlerinin herhangi bir birleşimi ile yazılabileceği biçime sahiptir - <keyword>:(istisna, parameteriki noktadan önceki parametre adını da içerir).
Sembol Bölümü anahtar kelimeleri
Aşağıdaki anahtar kelimeler yardım görüntüleyicide, "Açıklama" bölümünün altında ve "Beyan Edildi" bölümünün üstünde belirgin bölümler olarak görüntülenir. Dahil edildiğinde, yorumlarınıza istediğiniz sırayla dahil edebilseniz bile, sıraları aşağıda gösterildiği gibi sabitlenir.
Biçimlendirme Biçimlendirme Başvurusunun Sembol Bölüm Komutları bölümündeki bölüm anahtar sözcüklerinin ve bunların kullanım amaçlarının tam olarak belgelenmiş listesine bakın .
/// - parameters:
/// - <#parameter name#>:
/// - <#parameter name#>:
/// - throws:
/// - returns:
Alternatif olarak, her parametreyi şu şekilde yazabilirsiniz:
/// - parameter <#parameter name#>:
Sembol Açıklama Alan anahtar kelimeleri
Aşağıdaki anahtar kelime listesi , yardım görüntüleyicinin "Açıklama" bölümünün gövdesinde kalın başlıklar olarak görüntülenir. "Açıklama" bölümünün geri kalanında olduğu gibi, bunları yazdığınız sırada görürsünüz.
Tüm liste Erica Sadun'un bu mükemmel blog makalesinden açıklanmıştır . Ayrıca , Biçimlendirilmiş Biçimlendirme Başvurusunun Sembol Açıklama Alan Komutları bölümünde tam olarak belgelenmiş anahtar kelime listesine ve kullanım amaçlarına bakın .
Atıflar:
/// - author:
/// - authors:
/// - copyright:
/// - date:
Kullanılabilirlik:
/// - since:
/// - version:
Uyarılar:
/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:
Kalkınma Durumu:
/// - bug:
/// - todo:
/// - experiment:
Uygulama Nitelikleri:
/// - complexity:
İşlevsel Anlambilim:
/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:
Çapraz referans:
/// - seealso:
Belgeleri Dışa Aktarma
HTML belgeleri (Apple'ın kendi belgelerini taklit etmek için tasarlanmıştır), açık kaynaklı bir komut satırı yardımcı programı olan Jazzy kullanılarak satır içi belgelerden oluşturulabilir .
$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`
Bu NSHipster makalesinden alınan konsol örneği
