Nhận xét tài liệu được hỗ trợ nguyên bản trong Xcode, tạo tài liệu được hiển thị thông minh trong Trợ giúp nhanh (cả trong ⌥biểu tượng bật lên khi bật biểu tượng và trong Trình kiểm tra trợ giúp nhanh ⌥⌘2).
Nhận xét tài liệu biểu tượng hiện được dựa trên cùng một cú pháp Markdown được sử dụng bởi các nhận xét sân chơi phong phú, do đó, rất nhiều điều bạn có thể làm trong các sân chơi hiện có thể được sử dụng trực tiếp trong tài liệu mã nguồn.
Để biết chi tiết đầy đủ về cú pháp, xem Tham chiếu định dạng đánh dấu . Lưu ý rằng có một số khác biệt giữa cú pháp cho tài liệu biểu tượng & bình luận sân chơi phong phú; những điều này được chỉ ra trong tài liệu (ví dụ: trích dẫn khối chỉ có thể được sử dụng trong các sân chơi).
Dưới đây là một ví dụ và danh sách các yếu tố cú pháp hiện đang hoạt động cho các nhận xét tài liệu ký hiệu.
Cập nhật
Xcode 7 beta 4 ~ Đã thêm " - Throws: ..." dưới dạng mục danh sách cấp cao nhất xuất hiện cùng với các tham số và trả về mô tả trong Trợ giúp nhanh.
Xcode 7 beta 1 ~ Một số thay đổi đáng kể về cú pháp với Swift 2 - nhận xét tài liệu hiện dựa trên Markdown (giống như sân chơi).
Xcode 6.3 (6D570) ~ Văn bản thụt lề hiện được định dạng dưới dạng khối mã, với các vết lõm tiếp theo được lồng vào nhau. Dường như không thể để một dòng trống trong một khối mã như vậy - cố gắng làm như vậy dẫn đến việc văn bản được xử lý ở cuối dòng cuối cùng với bất kỳ ký tự nào trong đó.
Xcode 6.3 beta ~ Mã nội tuyến hiện có thể được thêm vào nhận xét tài liệu bằng cách sử dụng backticks.
Ví dụ cho 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."
}
Cú pháp cho Swift 2 (dựa trên Markdown )
Bình luận phong cách
Cả hai bình luận kiểu ///(nội tuyến) và /** */(khối) đều được hỗ trợ để tạo bình luận tài liệu. Trong khi cá nhân tôi thích phong cách /** */bình luận trực quan , thụt lề tự động của Xcode có thể phá hỏng định dạng cho kiểu nhận xét này khi sao chép / dán vì nó xóa khoảng trắng hàng đầu. Ví dụ:
/**
See sample usage:
let x = method(blah)
*/
Khi dán, thụt khối mã được loại bỏ và nó không còn được hiển thị dưới dạng mã:
/**
See sample usage:
let x = method(blah)
*/
Vì lý do này, tôi thường sử dụng ///và sẽ sử dụng nó cho phần còn lại của các ví dụ trong câu trả lời này.
Các yếu tố khối
Phần mở đầu:
/// # My Heading
hoặc là
/// My Heading
/// ==========
Phân nhóm:
/// ## My Subheading
hoặc là
/// My Subheading
/// -------------
Quy tắc ngang:
/// ---
Danh sách không có thứ tự (gạch đầu dòng):
/// - An item
/// - Another item
Bạn cũng có thể sử dụng +hoặc *cho các danh sách không có thứ tự, nó chỉ cần nhất quán.
Danh sách được sắp xếp (đánh số):
/// 1. Item 1
/// 2. Item 2
/// 3. Item 3
Khối mã:
/// for item in array {
/// print(item)
/// }
Một vết lõm của ít nhất bốn không gian được yêu cầu.
Yếu tố nội tuyến
Nhấn mạnh (in nghiêng):
/// Add like *this*, or like _this_.
Mạnh (đậm):
/// You can **really** make text __strong__.
Lưu ý rằng bạn không thể trộn dấu hoa thị ( *) và dấu gạch dưới ( _) trên cùng một phần tử.
Mã nội tuyến:
/// Call `exampleMethod(_:)` to demonstrate inline code.
Liên kết:
/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)
Hình ảnh:
/// 
URL có thể là URL web (sử dụng "http: //") hoặc URL đường dẫn tệp tuyệt đối (tôi dường như không thể có đường dẫn tệp tương đối để hoạt động).
Các URL cho liên kết và hình ảnh cũng có thể được tách ra khỏi thành phần nội tuyến để giữ tất cả các URL ở một nơi, có thể quản lý được:
/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg
Từ khóa
Ngoài định dạng Markdown, Xcode nhận ra các từ khóa đánh dấu khác để hiển thị nổi bật trong Trợ giúp nhanh. Các từ khóa đánh dấu này chủ yếu có định dạng - <keyword>:(ngoại lệ parameter, bao gồm tên tham số trước dấu hai chấm), trong đó từ khóa có thể được viết với bất kỳ sự kết hợp nào của các ký tự viết hoa / viết thường.
Từ khóa Phần biểu tượng
Các từ khóa sau được hiển thị dưới dạng các phần nổi bật trong trình xem trợ giúp, bên dưới phần "Mô tả" và phía trên phần "Khai báo trong". Khi được bao gồm, thứ tự của chúng được cố định như hiển thị bên dưới mặc dù bạn có thể đưa chúng vào bất kỳ thứ tự nào bạn muốn trong nhận xét của mình.
Xem danh sách tài liệu đầy đủ của các từ khóa phần và mục đích sử dụng của chúng trong phần Lệnh biểu tượng của tham chiếu định dạng đánh dấu .
/// - parameters:
/// - <#parameter name#>:
/// - <#parameter name#>:
/// - throws:
/// - returns:
Ngoài ra, bạn có thể viết từng tham số theo cách này:
/// - parameter <#parameter name#>:
Biểu tượng Mô tả Từ khóa trường
Danh sách các từ khóa sau đây được hiển thị dưới dạng các tiêu đề in đậm trong phần "Mô tả" của trình xem trợ giúp. Chúng sẽ xuất hiện theo bất cứ thứ tự nào bạn viết chúng, như với phần còn lại của phần "Mô tả".
Danh sách đầy đủ được diễn giải từ bài viết blog tuyệt vời này của Erica Sadun. Đồng thời xem danh sách từ khóa được ghi lại đầy đủ và mục đích sử dụng của chúng trong phần Lệnh mô tả trường biểu tượng của Tham chiếu định dạng đánh dấu .
Các bản phân phối:
/// - author:
/// - authors:
/// - copyright:
/// - date:
Khả dụng:
/// - since:
/// - version:
Lời khuyên:
/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:
Nhà nước phát triển:
/// - bug:
/// - todo:
/// - experiment:
Chất lượng thực hiện:
/// - complexity:
Chức năng ngữ nghĩa:
/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:
Tham chiếu chéo:
/// - seealso:
Tài liệu xuất khẩu
Tài liệu HTML (được thiết kế để bắt chước tài liệu riêng của Apple) có thể được tạo từ tài liệu nội tuyến bằng cách sử dụng Jazzy , một tiện ích dòng lệnh nguồn mở.
$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`
Ví dụ bảng điều khiển được lấy từ bài viết NSHipster này
