Biri Xcode 5'in yeni özellikleri özel bir açıklama sözdizimi ile kendi kod belgelemek yeteneğidir. Biçim doxygen'e benzer, ancak bu özelliklerin yalnızca bir alt kümesini desteklediği görülmektedir .

Hangi komutlar desteklenir, hangileri desteklenmez?
Kullanımlarından herhangi biri oksijenden farklı mıdır?

İşte Xcode 5.0.2'den beri bulduğum tüm seçeneklere bir örnek

Bu kodla oluşturuldu:

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

Notlar:

• Komutlar bir olmalı /** block */, /*! block */ya öneki ///ya //!.
• Komutlar @( headerdoc stili) veya \( doxygen stili) önekiyle çalışır. (Yani @bve \bher ikisi de aynı şeyi yapın.)
• Komutlar genellikle tanımladıkları öğeden önce gelir. (Eğer bir mülk belgelemek çalışıyorsanız Yani, yorum önce gelmelidir @propertymetin.) Onlar ile aynı satırda, sonradan gelebilir /*!<, /**<, //!<, ///<.
• Sınıflara, işlevlere, özelliklere ve değişkenlere belge ekleyebilirsiniz .
• Bu komutların tümü, dışındaki geçerli komutlar olduğunu belirtmek için koyu yeşil renkte görünür @returns.
• Belgelerinizdeki son değişiklikler görünmeden önce projenizi oluşturmanız (veya Xcode'u yeniden başlatmanız) gerekebilir.

Belgeleri nerede görebilirim:

1. Kod tamamlandığında, kısa metni göreceksiniz:

Bu kısa metni gösterecektir (biçimlendirme olmadan); kısa metin yoksa, ilk @block'a kadar tüm metinlerin bir birleşimini gösterecektir; hiçbiri yoksa (örneğin @return ile başlıyorsanız), o zaman tüm metni all @commands'ı keserek bitirir.

2. Bir tanımlayıcı adını Option tuşunu basılı tutarak tıklatın:

3. Hızlı Yardım Denetçisi panelinde

(İlk ekran görüntüsüne bakın.)

4. Doxygen'te

Xcode 5'teki komutlar Doxygen ile uyumlu olduğundan, belge dosyaları oluşturmak için Doxygen'i indirip kullanabilirsiniz.

Diğer notlar

Doxygen'e genel bir giriş ve Objective-C kodunun nasıl belgelendirileceği için bu sayfa iyi bir kaynak gibi görünüyor.

Desteklenen bazı komutların açıklamaları:

• @brief: açıklama alanının başına metin ekler ve kod tamamlanırken görüntülenecek tek metindir.

Aşağıdakiler işe yaramaz:

• \n: yeni satır oluşturmaz. Yeni satır oluşturmanın bir yolu, bu satırda hiçbir şey olmadığından emin olmaktır. Tek bir boşluk karakteri bile yok!
• \example

Aşağıdakiler desteklenmez (koyu yeşil renkte bile görünmezler):

• \anmak
• \ docbookonly
• \ enddocbookonly
• \ endinternal
• \ endrtfonly
• \ endsecreflist
• \ idlexcept
• \ mscfile
• \ refitem
• \ relatedalso
• \ rtfonly
• \ secreflist
• \kısa
• \ pasajı
• \içindekiler
• \ vhdlflow
• \ ~
• \"
• .
• ::
• \ |

Apple'a ayrılmış anahtar kelimeler:

Apple, yalnızca belgelerinde çalışan ayrılmış anahtar kelimeler kullanır. Koyu yeşil renkte görünseler de, Apple'ın yaptığı gibi kullanamayız. Apple'ın AVCaptureOutput.h gibi dosyalarda kullanımıyla ilgili örnekleri görebilirsiniz.

Bu anahtar kelimelerin bazılarının listesi:

• @abstract, @availibility, @class, @discussion, @depecated, @method, @property, @protocol, @related, @ref.

En iyi ihtimalle, anahtar kelime Açıklama alanında yeni bir satıra neden olur (ör. @Discussion). En kötü ihtimalle, anahtar kelime ve onu izleyen herhangi bir metin hızlı yardımda görünmez (ör. @ Sınıf).

Swift 2.0 aşağıdaki sözdizimini kullanır:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

@paramŞimdi nasıl olduğuna dikkat edin- parameter .

Artık belgelerinize madde işaretleri de ekleyebilirsiniz:

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

Senseful:

Belgelerinizde en son değişiklikler görünmeden önce projenizi oluşturmanız gerekebilir.

Bazen bu benim için yeterli değildi. Xcode'un kapatılması ve projenin yedeklenmesi genellikle bu durumları düzeltir.

Ayrıca .h ve .m dosyalarında farklı sonuçlar alıyorum. Doküman yorumları bir başlık dosyasındayken yeni satırlar alamıyorum.

Swift 2.0 için biçimlendirmenin çoğu değişti (Xcode7 ß3'ten itibaren, ß4'te de geçerlidir)

onun yerine :param: thing description of thing (Swift 1.2'de olduğu gibi)

şimdi - parameter thing: description of thing

Çoğu anahtar kelime ile değiştirilmiştir - [keyword]: [description]yerine :[keyword]: [description]. İşi yok anahtar kelimelerin Şu anda liste içerir abstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, related, ref.