डॉक्यूमेंटेशन टिप्पणियों का समर्थन मूल रूप से Xcode में किया जाता है, क्विक हेल्प में ⌥स्मार्टली रेंडर किए गए डॉक्यूमेंटेशन का निर्माण करते हैं ( पॉपओवर में जब-जब सिंबल का निर्माण होता है, और क्विक हेल्प इंस्पेक्टर में दोनों)⌥⌘2 )।
प्रतीक दस्तावेजीकरण टिप्पणियां अब उसी मार्काडाउन सिंटैक्स पर आधारित हैं, जिसका उपयोग रिच प्लेग्राउंड टिप्पणियों द्वारा किया जाता है, इसलिए आप जो खेल के मैदानों में कर सकते हैं उसका बहुत कुछ अब सीधे स्रोत कोड प्रलेखन में उपयोग किया जा सकता है।
सिंटैक्स के पूर्ण विवरण के लिए, मार्कअप स्वरूपण संदर्भ देखें । ध्यान दें कि अमीर खेल के मैदान टिप्पणियों और प्रतीक प्रलेखन के लिए वाक्यविन्यास के बीच कुछ विसंगतियां हैं; ये दस्तावेज़ में इंगित किए गए हैं (जैसे ब्लॉक उद्धरण केवल खेल के मैदानों में उपयोग किए जा सकते हैं)।
नीचे एक उदाहरण और वाक्यविन्यास तत्वों की एक सूची है जो वर्तमान में प्रतीक प्रलेखन टिप्पणियों के लिए काम करते हैं।
अपडेट
Xcode 7 बीटा 4 ~ जोड़ा गया " - Throws: ..." एक शीर्ष-स्तरीय सूची आइटम के रूप में जो मापदंडों के साथ प्रकट होता है और त्वरित सहायता में विवरण लौटाता है।
Xcode 7 बीटा 1 ~ स्विफ्ट 2 के साथ वाक्य रचना में कुछ महत्वपूर्ण बदलाव - मार्कडाउन (खेल के मैदानों के समान) के आधार पर अब प्रलेखन टिप्पणियां।
Xcode 6.3 (6D570) ~ इंडेंट किए गए टेक्स्ट को अब कोड ब्लॉक के रूप में स्वरूपित किया गया है, जिसमें बाद के इंडेंटेशन नेस्टेड हैं। इस तरह के कोड ब्लॉक में एक खाली लाइन को छोड़ना संभव प्रतीत नहीं होता है - पाठ में ऐसा करने की कोशिश करते हुए इसमें किसी भी वर्ण के साथ अंतिम पंक्ति के अंत में टैकल किया जा रहा है।
Xcode 6.3 बीटा ~ इनलाइन कोड को अब बैकटिक्स का उपयोग करके प्रलेखन टिप्पणियों में जोड़ा जा सकता है।
स्विफ्ट 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."
}
स्विफ्ट 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)
/// }
कम से कम चार स्थानों का इंडेंटेशन आवश्यक है।
इनलाइन तत्वों
जोर (इटैलिक):
/// 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)
इमेजिस:
/// 
URL या तो एक वेब URL हो सकता है ("http: //" का उपयोग करके) या एक निरपेक्ष फ़ाइल पथ URL (मैं काम करने के लिए सापेक्ष फ़ाइल पथ प्राप्त नहीं कर सकता)।
लिंक और छवियों के URL को इनलाइन तत्व से अलग भी किया जा सकता है ताकि सभी URL को एक, प्रबंधनीय जगह पर रखा जा सके:
/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg
कीवर्ड
मार्काड प्रारूपण के अलावा, Xcode अन्य मार्कअप कीवर्ड को त्वरित सहायता में प्रमुखता से प्रदर्शित करने के लिए पहचानता है। ये मार्कअप कीवर्ड ज्यादातर प्रारूप लेते हैं - <keyword>:(अपवाद हैparameter , जिसमें बृहदान्त्र से पहले पैरामीटर नाम भी शामिल है), जहां कीवर्ड को अपरकेस / लोअरकेस वर्णों के किसी भी संयोजन के साथ लिखा जा सकता है।
प्रतीक खंड खोजशब्द
"विवरण" खंड के नीचे, और "घोषित में" अनुभाग के ऊपर, मदद कीवर्ड में निम्नलिखित कीवर्ड प्रमुख वर्गों के रूप में प्रदर्शित किए जाते हैं। जब शामिल किया जाता है, तो उनका क्रम नीचे प्रदर्शित होता है, भले ही आप उन्हें अपनी टिप्पणी में जिस भी क्रम में चाहें शामिल कर सकते हैं।
मार्कअप प्रारूपण संदर्भ के प्रतीक अनुभाग कमांड अनुभाग में अनुभाग कीवर्ड और उनके इच्छित उपयोगों की पूरी तरह से प्रलेखित सूची देखें ।
/// - parameters:
/// - <#parameter name#>:
/// - <#parameter name#>:
/// - throws:
/// - returns:
वैकल्पिक रूप से, आप प्रत्येक पैरामीटर को इस तरह से लिख सकते हैं:
/// - parameter <#parameter name#>:
प्रतीक विवरण फ़ील्ड कीवर्ड
कीवर्ड की निम्न सूची के रूप में प्रदर्शित कर रहे हैं बोल्ड शीर्षकों मदद दर्शक के "विवरण" अनुभाग के मुख्य भाग में। आप उन्हें जिस भी क्रम में लिखते हैं, बाकी "विवरण" खंड के साथ दिखाई देगा।
एरिका सदुन के इस उत्कृष्ट ब्लॉग लेख से पूरी सूची पारंगत हो गई। साथ ही मार्कअप स्वरूपण संदर्भ के प्रतीक विवरण फ़ील्ड कमांड अनुभाग में खोजशब्दों और उनके इच्छित उपयोगों की पूरी तरह से प्रलेखित सूची देखें ।
विशेषताएं:
/// - author:
/// - authors:
/// - copyright:
/// - date:
उपलब्धता:
/// - since:
/// - version:
admonitions:
/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:
विकास की स्थिति:
/// - bug:
/// - todo:
/// - experiment:
कार्यान्वयन की योग्यता:
/// - complexity:
कार्यात्मक शब्दार्थ:
/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:
प्रति संदर्भ:
/// - seealso:
निर्यात प्रलेखन
HTML डॉक्यूमेंटेशन (Apple के खुद के डॉक्यूमेंटेशन की नकल करने के लिए बनाया गया) इनलाइन डॉक्यूमेंट से Jazzy , एक ओपन-सोर्स कमांड-लाइन यूटिलिटी का उपयोग करके उत्पन्न किया जा सकता है ।
$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`
इस NSHipster लेख से लिया गया कंसोल उदाहरण
