Jakie są nowe polecenia dokumentacji dostępne w Xcode 5? [Zamknięte]

186

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?

Rozsądny
źródło

Odpowiedzi:

419

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

wprowadź opis zdjęcia tutaj

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:

wprowadź opis zdjęcia tutaj

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:

wprowadź opis zdjęcia tutaj

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).

Rozsądny
źródło
4
Dziękuję za opis. Mam nadzieję, że Apple skopiuje go do instrukcji Xcode;)
TheGrumpyCoda
3
Używanie symbolu @ zamiast \ również działa.
Drewsmits,
8
+1 Świetna kolekcja! Jak dodać link do szybkiej pomocy innej klasy w szybkiej pomocy?
Selvin
3
Możesz także użyć @cdo wyświetlenia następnego słowa w tekście maszyny do pisania, jak w Returns an @c NSString or @c nil..
Matthew Quiros
7
Czy znalazłeś sposób na wyświetlenie adresu URL w wyskakującym okienku z wciśniętym klawiszem Option? Na przykład, jeśli klikniesz opcję -[CADisplayLink addToRunLoop:forMode:], opis zawiera nazwane łącza do innych klas (ale przypuszczam, że przydatne byłyby również adresy URL znajdujące się w sieci).
Zev Eisenberg,
16

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
źródło
9

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.

weezma2004
źródło
5

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.

rękawice
źródło