ความคิดเห็นของเอกสารได้รับการสนับสนุนใน Xcode โดยกำเนิดการสร้างเอกสารที่แสดงผลอย่างฉลาดในวิธีใช้ด่วน (ทั้งในป๊อป⌥โอเวอร์เมื่อ - คลิกสัญลักษณ์และใน Quick Help Inspector ⌥⌘2)
การแสดงความคิดเห็นเอกสารสัญลักษณ์ในขณะนี้มีพื้นฐานมาจากไวยากรณ์ Markdownเดียวกับที่ใช้โดยข้อคิดเห็นของสนามเด็กเล่นที่อุดมไปด้วยดังนั้นสิ่งที่คุณสามารถทำได้ในสนามเด็กเล่นตอนนี้สามารถนำมาใช้โดยตรงในเอกสารรหัสต้นฉบับ
สำหรับรายละเอียดของไวยากรณ์ดูMarkup การจัดรูปแบบการอ้างอิง โปรดทราบว่ามีความแตกต่างระหว่างไวยากรณ์สำหรับความคิดเห็นที่อุดมไปด้วยสนามเด็กเล่นและเอกสารสัญลักษณ์; สิ่งเหล่านี้ถูกระบุไว้ในเอกสาร (เช่นราคาบล็อกสามารถใช้ในสนามเด็กเล่นเท่านั้น)
ด้านล่างนี้เป็นตัวอย่างและรายการองค์ประกอบของไวยากรณ์ที่ทำงานกับข้อคิดเห็นเอกสารสัญลักษณ์ได้ในปัจจุบัน
อัพเดท
Xcode 7 beta 4 ~เพิ่ม " - Throws: ..." เป็นรายการในรายการระดับบนสุดซึ่งจะปรากฏข้างพารามิเตอร์และส่งคืนคำอธิบายในวิธีใช้ด่วน
Xcode 7 beta 1 ~การเปลี่ยนแปลงที่สำคัญบางอย่างกับไวยากรณ์ด้วย Swift 2 - ความคิดเห็นเอกสารประกอบในขณะนี้ขึ้นอยู่กับ Markdown (เช่นเดียวกับสนามเด็กเล่น)
Xcode 6.3 (6D570) ~ข้อความที่เยื้องในขณะนี้ได้รับการจัดรูปแบบเป็นบล็อคโค้ดโดยมีการเยื้องในภายหลัง ดูเหมือนจะเป็นไปไม่ได้ที่จะปล่อยให้บรรทัดว่างในบล็อกโค้ดดังกล่าว - พยายามทำเช่นนั้นส่งผลให้ข้อความถูกตรึงไว้ที่ท้ายบรรทัดสุดท้ายด้วยอักขระใด ๆ ในนั้น
Xcode 6.3 beta ~ Inline Code สามารถเพิ่มลงในข้อคิดเห็นเอกสารโดยใช้ backticks
ตัวอย่างสำหรับ 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."
}
ไวยากรณ์สำหรับ Swift 2 (อิงจากMarkdown )
สไตล์ความคิดเห็น
ทั้งสอง///(อินไลน์) และ/** */(บล็อก) ความเห็นสไตล์ได้รับการสนับสนุนในการผลิตเอกสารแสดงความคิดเห็น ในขณะที่ฉันชอบสไตล์การ/** */แสดงความคิดเห็นเป็นการส่วนตัวการย่อหน้าอัตโนมัติของ 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#>:
สัญลักษณ์คำอธิบายฟิลด์คำสำคัญ
รายการคำหลักต่อไปนี้จะแสดงเป็นส่วนหัวที่เป็นตัวหนาในส่วนของ "คำอธิบาย" ของตัวแสดงวิธีใช้ พวกเขาจะปรากฏตามลำดับที่คุณเขียนไว้เช่นเดียวกับส่วนที่เหลือของส่วน "คำอธิบาย"
รายการทั้งหมดถอดความจากบทความบล็อกยอดเยี่ยมนี้โดย Erica Sadun นอกจากนี้ยังดูรายการเอกสารครบถ้วนของคำและการใช้ตั้งใจของพวกเขาในสัญลักษณ์ส่วนของคำอธิบายฟิลด์คำสั่งของมาร์กอัปการจัดรูปแบบการอ้างอิง
การอ้างเหตุผล:
/// - author:
/// - authors:
/// - copyright:
/// - date:
สถานะ:
/// - since:
/// - version:
ค่อนขอด:
/// - 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 นี้
