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. @b
I \b
oboje robią to samo.)
- Polecenia zwykle występują przed opisywanym przedmiotem. (Tj jeśli próbuje udokumentować właściwości, komentarz musi przyjść przed
@property
tekś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).
@c
do wyświetlenia następnego słowa w tekście maszyny do pisania, jak wReturns an @c NSString or @c nil.
.-[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).Swift 2.0 używa następującej składni:
Zauważ, jak
@param
jest teraz- parameter
.Możesz teraz także dołączać pociski do swojej dokumentacji:
źródło
Rozsądny:
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.
źródło
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ódło