Eine der neuen Funktionen von Xcode 5 ist die Möglichkeit, Ihren eigenen Code mit einer speziellen Kommentarsyntax zu dokumentieren. Das Format ähnelt doxygen, scheint jedoch nur eine Teilmenge dieser Funktionen zu unterstützen .

Welche Befehle werden unterstützt und welche nicht?
Unterscheiden sich ihre Verwendungen von Sauerstoff?

Hier ist ein Beispiel für alle Optionen, die ich ab Xcode 5.0.2 gefunden habe

Das wurde mit diesem Code generiert:

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

Anmerkungen:

• Die Befehle in a sein muss /** block */, /*! block */oder mit dem Präfix ///oder //!.
• Die Befehle arbeiten mit dem Präfix@ ( Headerdoc- Stil) oder \( Doxygen- Stil). (Ie @bund \bbeide das gleiche tun.)
• Die Befehle stehen normalerweise vor dem Element, das sie beschreiben. (Dh , wenn Sie versuchen , eine Eigenschaft zu dokumentieren, muss der Kommentar kommen vor dem @propertyText.) Sie können kommen , danach auf der gleichen Linie, mit /*!<, /**<, //!<, ///<.
• Sie können Klassen, Funktionen, Eigenschaften und Variablen Dokumentation hinzufügen .
• Alle diese Befehle werden in dunkelgrünem Text angezeigt, um anzuzeigen, dass es sich um gültige Befehle handelt, mit Ausnahme von @returns.
• Möglicherweise müssen Sie Ihr Projekt erstellen (oder Xcode neu starten), bevor die neuesten Änderungen an Ihrer Dokumentation angezeigt werden.

Wo kann man die Dokumentation sehen:

1. Während der Code-Vervollständigung wird der kurze Text angezeigt:

Dies zeigt den kurzen Text (ohne Formatierung); Wenn kein kurzer Text vorhanden ist, wird eine Verkettung des gesamten Textes bis zum ersten @block angezeigt. Wenn keine vorhanden ist (z. B. wenn Sie mit @return beginnen), wird der gesamte Text entfernt, wobei alle @commands entfernt werden.

2. Klicken Sie bei gedrückter Wahltaste auf einen Bezeichnernamen:

3. Im Bereich Quick Help Inspector

(Siehe ersten Screenshot.)

4. In Sauerstoff

Da die Befehle in Xcode 5 mit Doxygen kompatibel sind, können Sie Doxygen herunterladen und zum Generieren von Dokumentationsdateien verwenden.

Weitere Hinweise

Für eine allgemeine Einführung in Doxygen und zum Dokumentieren von Objective-C-Code scheint diese Seite eine gute Ressource zu sein.

Beschreibungen einiger unterstützter Befehle:

• @brief: fügt Text am Anfang des Beschreibungsfelds ein und ist der einzige Text, der während der Code-Vervollständigung angezeigt wird.

Folgendes funktioniert nicht:

• \n: generiert keine Newline. Eine Möglichkeit, eine neue Zeile zu erstellen, besteht darin, sicherzustellen, dass sich nichts in dieser Zeile befindet. Nicht einmal ein einziges Leerzeichen!
• \example

Folgendes wird nicht unterstützt (sie erscheinen nicht einmal dunkelgrün):

• \zitieren
• \ docbookonly
• \ enddocbookonly
• \ endinternal
• \ endrtfonly
• \ endsecreflist
• \ idlexcept
• \ mscfile
• \ refitem
• \ relatedauch
• Nur
• \ secreflist
• \kurz
• \ snippet
• \Inhaltsverzeichnis
• \ vhdlflow
• \ ~
• ""
• .
• :: ::
• \ |

Von Apple reservierte Keywords:

Apple verwendet scheinbar reservierte Schlüsselwörter, die nur in der Dokumentation funktionieren. Obwohl sie dunkelgrün erscheinen, können wir sie anscheinend nicht wie Apple verwenden. Beispiele für die Verwendung von Apple finden Sie in Dateien wie AVCaptureOutput.h.

Hier ist eine Liste einiger dieser Schlüsselwörter:

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

Im besten Fall verursacht das Schlüsselwort eine neue Zeile im Feld Beschreibung (z. B. @discussion). Im schlimmsten Fall werden das Schlüsselwort und der darauf folgende Text nicht in der Schnellhilfe angezeigt (z. B. @class).

Swift 2.0 verwendet die folgende Syntax:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

Beachten Sie, wie @parames jetzt ist - parameter.

Sie können jetzt auch Aufzählungszeichen in Ihre Dokumentation aufnehmen:

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

Sinnvoll:

Möglicherweise müssen Sie Ihr Projekt erstellen, bevor die neuesten Änderungen an Ihrer Dokumentation angezeigt werden.

Manchmal hat mir das nicht gereicht. Das Schließen von Xcode und das Öffnen des Projekts sichern normalerweise diese Fälle.

Ich erhalte auch unterschiedliche Ergebnisse in .h-Dateien und .m-Dateien. Ich kann keine neuen Zeilen erhalten, wenn sich die Dokumentationskommentare in einer Header-Datei befinden.

Der größte Teil der Formatierung hat sich für Swift 2.0 geändert (ab Xcode7 ß3, auch in ß4)

statt :param: thing description of thing (wie in Swift 1.2)

ist das jetzt - parameter thing: description of thing

Die meisten Schlüsselwörter wurden durch - [keyword]: [description]anstelle von ersetzt :[keyword]: [description]. Derzeit ist die Liste der Schlüsselwörter , die keine Arbeit tun enthält, abstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, related, ref.