Jedną z nowych funkcji Xcode 5 jest możliwość udokumentowania własnego kodu za pomocą specjalnej składni komentarzy. Format jest podobny do doksygen, ale wydaje się, że obsługuje tylko podzbiór tych funkcji .

Które polecenia są obsługiwane, a które nie?
Czy którekolwiek z ich zastosowań różnią się od doksygen?

Oto przykład wszystkich opcji, które znalazłem od Xcode 5.0.2

Wygenerowano za pomocą tego kodu:

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

Uwagi:

• Polecenia muszą być w /** block */, /*! block */lub z przedrostkiem ///lub //!.
• Polecenia działają z prefiksem@ ( styl headerdoc ) lub \( styl doxygen ). (Tj. @bI \boboje robią to samo.)
• Polecenia zwykle występują przed opisywanym przedmiotem. (Tj jeśli próbuje udokumentować właściwości, komentarz musi przyjść przed @propertytekście). Mogą przyjść później, na tej samej linii, z /*!<, /**<, //!<, ///<.
• Możesz dodawać dokumentację do klas, funkcji, właściwości i zmiennych .
• Wszystkie te polecenia są wyświetlane ciemnozielonym tekstem, co oznacza, że ​​są poprawnymi poleceniami, z wyjątkiem @returns.
• Konieczne może być zbudowanie projektu (lub ponowne uruchomienie Xcode), zanim pojawią się najnowsze zmiany w dokumentacji.

Gdzie zobaczyć dokumentację:

1. Po zakończeniu kodu zobaczysz krótki tekst:

Spowoduje to wyświetlenie krótkiego tekstu (bez formatowania); jeśli nie istnieje krótki tekst, pokaże on konkatenację całego tekstu aż do pierwszego @bloku; jeśli nie istnieje (np. zaczynasz od @return), wówczas konkatuje cały tekst, usuwając wszystkie @ komendy.

2. Kliknięcie opcji nazwy identyfikatora:

3. W panelu Inspektora szybkiej pomocy

(Zobacz pierwszy zrzut ekranu.)

4. W Doxygen

Ponieważ polecenia w Xcode 5 są zgodne z Doxygen, możesz pobrać i używać Doxygen do generowania plików dokumentacji.

Inne notatki

Ogólne wprowadzenie do Doxygen i dokumentowanie kodu Celu C, ta strona wydaje się dobrym źródłem.

Opisy niektórych obsługiwanych poleceń:

• @brief: wstawi tekst na początku pola opisu i jest jedynym tekstem, który pojawi się podczas uzupełniania kodu.

Następujące nie działają:

• \n: nie generuje nowego wiersza. Jednym ze sposobów utworzenia nowej linii jest upewnienie się, że nic nie znajduje się na tej linii. Ani jednej spacji!
• \example

Następujące elementy nie są obsługiwane (nawet nie są wyświetlane w kolorze ciemnozielonym):

• \cytować
• \ docbookonly
• \ enddocbookonly
• endinternal
• \ endrtfonly
• \ endsecreflist
• \ idlexcept
• \ mscfile
• \ refitem
• związane również
• rtfonly
• \ secreflist
• \krótki
• \skrawek
• \ tableofcontents
• \ vhdlflow
• \ ~
• \ ”
• .
• ::
• \ |

Zastrzeżone słowa kluczowe Apple:

Apple używa słów kluczowych, które wydają się zastrzeżone, które działają tylko w ich dokumentacji. Chociaż są wyświetlane w kolorze ciemnozielonym, wygląda na to, że nie możemy ich używać tak jak Apple. Możesz zobaczyć przykłady użycia Apple w plikach takich jak AVCaptureOutput.h.

Oto lista niektórych z tych słów kluczowych:

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

W najlepszym razie słowo kluczowe spowoduje nową linię w polu Opis (np. @Dyskusja). W najgorszym przypadku słowo kluczowe i następujący po nim tekst nie pojawią się w szybkiej pomocy (np. @Class).

Swift 2.0 używa następującej składni:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

Zauważ, jak @paramjest teraz - parameter.

Możesz teraz także dołączać pociski do swojej dokumentacji:

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

Rozsądny:

Konieczne może być zbudowanie projektu przed pojawieniem się najnowszych zmian w dokumentacji.

Czasami to mi nie wystarczało. Zamknięcie Xcode i ponowne otwarcie projektu zwykle rozwiązuje te problemy.

Otrzymuję również różne wyniki w plikach .h i .m. Nie mogę uzyskać nowych wierszy, gdy komentarze do dokumentacji znajdują się w pliku nagłówkowym.

Większość formatowania zmieniła się dla Swift 2.0 (od Xcode7 ß3, również prawda w ß4)

zamiast :param: thing description of thing (jak to było w Swift 1.2)

to jest teraz - parameter thing: description of thing

Większość słów kluczowych zastąpiono - [keyword]: [description]zamiast :[keyword]: [description]. Obecnie lista słów kluczowych, które nie działają obejmuje, abstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, related, ref.