Một trong những tính năng mới của Xcode 5 là khả năng ghi lại mã của riêng bạn bằng cú pháp nhận xét đặc biệt. Định dạng tương tự doxygen, nhưng dường như chỉ hỗ trợ một tập hợp con các tính năng đó .

Những lệnh nào được hỗ trợ, và lệnh nào không?
Có bất kỳ công dụng của họ khác với doxygen?

Dưới đây là một ví dụ về tất cả các tùy chọn tôi đã tìm thấy kể từ Xcode 5.0.2

Điều đó đã được tạo ra với mã này:

/** First line text.

 Putting \\n doesn't create a new line.\n One way to create a newline is by making sure nothing is on that line. Not even a single space character!

 @a Italic text @em with @@a or @@em.

 @b Bold text with @@b.

 @p Typewritter font @c with @@p or @@c.

 Backslashes and must be escaped: C:\\foo.

 And so do @@ signs: user@@example.com

 Some more text.
 @brief brief text
 @attention attention text
 @author author text
 @bug bug text
 @copyright copyright text
 @date date text
 @invariant invariant text
 @note note text
 @post post text
 @pre pre text
 @remarks remarks text
 @sa sa text
 @see see text
 @since since text
 @todo todo text
 @version version text
 @warning warning text

 @result result text
 @return return text
 @returns returns text


 @code
// code text
while (someCondition) {
    NSLog(@"Hello");
    doSomething();
}@endcode
 Last line text.

 @param param param text
 @tparam tparam tparam text
 */
- (void)myMethod {}

Ghi chú:

• Các lệnh phải ở trong một /** block */, /*! block */hoặc bắt đầu bằng ///hoặc //!.
• Các lệnh làm việc với @( headerdoc phong cách) hoặc \( doxygen phong cách) tiền tố. (Tức là @bvà\b cả hai làm điều tương tự.)
• Các lệnh thường đến trước mục mà chúng đang mô tả. (Ví dụ nếu bạn đang cố gắng ghi lại một tài sản, nhận xét phải đến trước khi @propertyvăn bản.) Họ có thể đến sau đó, trên cùng một dòng, với /*!<, /**<, //!<, ///<.
• Bạn có thể thêm tài liệu vào các lớp, hàm, thuộc tính và biến .
• Tất cả các lệnh này xuất hiện trong văn bản màu xanh đậm để biểu thị rằng chúng là các lệnh hợp lệ, ngoại trừ @returns.
• Bạn có thể cần xây dựng dự án của mình (hoặc khởi động lại Xcode) trước khi những thay đổi mới nhất đối với tài liệu của bạn xuất hiện.

Nơi để xem tài liệu:

1. Trong quá trình hoàn tất mã, bạn sẽ thấy văn bản ngắn gọn:

Điều này sẽ hiển thị văn bản ngắn gọn (không có định dạng); nếu không có văn bản ngắn gọn nào tồn tại, nó sẽ hiển thị nối tất cả các văn bản cho đến @block đầu tiên; nếu không tồn tại (ví dụ: bạn bắt đầu bằng @return), thì nó sẽ nối tất cả các văn bản loại bỏ tất cả @commands.

2. Nhấp vào tùy chọn tên định danh:

3. Trong bảng Thanh tra Trợ giúp Nhanh

(Xem ảnh chụp màn hình đầu tiên.)

4. Ở Doxygen

Vì các lệnh trong Xcode 5 tương thích với Doxygen, bạn có thể tải xuống và sử dụng Doxygen để tạo tệp tài liệu.

Ghi chú khác

Để có giới thiệu chung về Doxygen và cách ghi lại mã Objective-C, trang này có vẻ như là một tài nguyên tốt.

Mô tả một số lệnh được hỗ trợ:

• @brief: sẽ chèn văn bản vào đầu trường mô tả và là văn bản duy nhất sẽ xuất hiện trong quá trình hoàn tất mã.

Những điều sau đây không hoạt động:

• \n: không tạo ra một dòng mới. Một cách để tạo một dòng mới là đảm bảo không có gì trên dòng đó. Thậm chí không phải là một nhân vật không gian duy nhất!
• \example

Những điều sau đây không được hỗ trợ (chúng thậm chí không xuất hiện trong màu xanh đậm):

• trích dẫn
• \ docbookonly
• \ enddocbookonly
• \ nội bộ
• cuối cùng
• \ endecreflist
• \ idlexcept
• \ mscfile
• \ giới thiệu
• \ liên quan
• \ rtfonly
• \ bí mật
• \ngắn
• đoạn trích
• \mục lục
• \ vhdlflow
• \ ~
• \ "
• .
• ::
• \ |

Từ khóa dành riêng của Apple:

Apple sử dụng những gì dường như là các từ khóa dành riêng chỉ hoạt động trong tài liệu của họ. Mặc dù chúng xuất hiện với màu xanh đậm, nhưng có vẻ như chúng ta không thể sử dụng chúng như Apple. Bạn có thể xem các ví dụ về việc sử dụng của Apple trong các tệp như AVCaptureOutput.h.

Dưới đây là danh sách một số từ khóa:

• @abab, @availibility, @ class, @discussion, @deprecated, @method, @property, @protatio, @related, @ref.

Tốt nhất, từ khóa sẽ gây ra một dòng mới trong trường Mô tả (ví dụ: @discussion). Tệ nhất, từ khóa và bất kỳ văn bản nào theo sau nó sẽ không xuất hiện trong phần trợ giúp nhanh (ví dụ: @ class).

Swift 2.0 sử dụng cú pháp sau:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

Chú ý @parambây giờ thế nào- parameter .

Bây giờ bạn cũng có thể bao gồm các viên đạn trong tài liệu của bạn:

/**
        - square(5) = 25
        - square(10) = 100
    */

Ý thức:

Bạn có thể cần xây dựng dự án của mình trước khi những thay đổi mới nhất đối với tài liệu của bạn xuất hiện.

Đôi khi điều này là không đủ cho tôi. Đóng Xcode và mở dự án sao lưu thường khắc phục các trường hợp đó.

Tôi cũng nhận được kết quả khác nhau trong tệp .h và tệp .m. Tôi không thể nhận được dòng mới khi các nhận xét tài liệu nằm trong tệp tiêu đề.

Hầu hết các định dạng đã thay đổi cho Swift 2.0 (kể từ Xcode7 ß3, cũng đúng trong ß4)

thay vì :param: thing description of thing (như trong Swift 1.2)

nó bây giờ là - parameter thing: description of thing

Hầu hết các từ khóa đã được thay thế bằng - [keyword]: [description]thay vì :[keyword]: [description]. Hiện nay danh sách các từ khóa mà không làm công việc bao gồm, abstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, related, ref.