Salah satu fitur baru Xcode 5 adalah kemampuan untuk mendokumentasikan kode Anda sendiri dengan sintaks komentar khusus. Formatnya mirip dengan doxygen, tetapi tampaknya hanya mendukung sebagian dari fitur-fitur itu .

Perintah mana yang didukung, dan mana yang tidak?
Apakah ada di antara penggunaannya yang berbeda dengan oksigen?

Ini adalah contoh dari semua opsi yang saya temukan pada Xcode 5.0.2

Itu dihasilkan dengan kode ini:

/** 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 {}

Catatan:

• Perintah harus dalam /** block */, /*! block */atau diawali dengan ///atau //!.
• Perintah bekerja dengan awalan@ ( gaya headerdoc ) atau \( gaya doxygen ). (Yaitu @bdan \bkeduanya melakukan hal yang sama.)
• Perintah biasanya datang sebelum item yang mereka gambarkan. (Yaitu jika Anda mencoba untuk mendokumentasikan properti, komentar harus datang sebelum @propertyteks.) Mereka bisa datang setelah itu, pada baris yang sama, dengan /*!<, /**<, //!<, ///<.
• Anda dapat menambahkan dokumentasi ke kelas, fungsi, properti, dan variabel .
• Semua perintah ini muncul dalam teks hijau gelap untuk menandakan bahwa itu adalah perintah yang valid, kecuali untuk @returns.
• Anda mungkin perlu membangun proyek Anda (atau memulai ulang Xcode) sebelum perubahan terbaru pada dokumentasi Anda muncul.

Tempat melihat dokumentasi:

1. Selama kode selesai, Anda akan melihat teks singkat:

Ini akan menampilkan teks singkat (tanpa format); jika tidak ada teks singkat, itu akan menampilkan gabungan dari semua teks hingga @block pertama; jika tidak ada (misalnya Anda mulai dengan @return), maka itu akan menyatukan semua teks yang menghapus semua @ perintah.

2. Opsi-mengklik nama pengidentifikasi:

3. Pada panel Inspektur Bantuan Cepat

(Lihat tangkapan layar pertama.)

4. Dalam Doxygen

Karena perintah dalam Xcode 5 kompatibel dengan Doxygen, Anda bisa mengunduh dan menggunakan Doxygen untuk menghasilkan file dokumentasi.

Catatan lain

Untuk pengantar umum tentang Doxygen dan cara mendokumentasikan kode Objective-C, halaman ini sepertinya merupakan sumber yang bagus.

Deskripsi beberapa perintah yang didukung:

• @brief: akan menyisipkan teks di awal bidang deskripsi, dan merupakan satu-satunya teks yang akan muncul selama penyelesaian kode.

Berikut ini tidak berfungsi:

• \n: tidak menghasilkan baris baru. Salah satu cara untuk membuat baris baru adalah dengan memastikan tidak ada yang di baris itu. Bahkan tidak ada karakter ruang tunggal!
• \example

Berikut ini tidak didukung (mereka bahkan tidak muncul dalam warna hijau gelap):

• \mengutip
• \ docbookonly
• \ enddocbookonly
• \ endinternal
• \ endrtfonly
• \ daftar akhir
• \ idlexcept
• \ mscfile
• \ refitem
• \ relatedalso
• Hanya saja
• \ secreflist
• \pendek
• \potongan
• \Daftar Isi
• \ vhdlflow
• \ ~
• \ "
• .
• ::
• \ |

Kata kunci milik Apple:

Apple menggunakan kata kunci yang tampaknya dilindungi undang-undang yang hanya berfungsi dalam dokumentasi mereka. Meskipun mereka muncul dalam warna hijau tua, sepertinya kita tidak bisa menggunakannya seperti Apple. Anda dapat melihat contoh penggunaan Apple dalam file seperti AVCaptureOutput.h.

Berikut adalah daftar dari beberapa kata kunci tersebut:

• @ ekstrak, @ ketersediaan, @ kelas, @ diskus, @deprecated, @method, @property, @protocol, @ terkait, @ref.

Paling-paling, kata kunci akan menyebabkan baris baru di bidang Deskripsi (mis. Diskusi @). Paling buruk, kata kunci dan teks apa pun yang mengikutinya tidak akan muncul dalam bantuan cepat (mis. @Class).

Swift 2.0 menggunakan sintaks berikut:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

Perhatikan bagaimana @paramsekarang - parameter.

Anda juga dapat memasukkan peluru ke dalam dokumentasi Anda:

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

Masuk akal:

Anda mungkin perlu membangun proyek Anda sebelum perubahan terbaru pada dokumentasi Anda muncul.

Terkadang ini belum cukup bagi saya. Menutup Xcode dan membuka kembali proyek biasanya memperbaiki kasus-kasus itu.

Saya juga mendapatkan hasil berbeda dalam file .h dan file .m. Saya tidak bisa mendapatkan baris baru ketika komentar dokumentasi ada dalam file header.

Sebagian besar pemformatan telah berubah untuk Swift 2.0 (pada Xcode7 ß3, juga berlaku di ß4)

bukannya :param: thing description of thing (seperti di Swift 1.2)

sekarang - parameter thing: description of thing

Sebagian besar kata kunci telah digantikan oleh - [keyword]: [description]alih-alih :[keyword]: [description]. Saat ini daftar kata kunci yang tidak kerja meliputi, abstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, related, ref.