it-swarm.com.de

Welche neuen Dokumentationsbefehle sind in Xcode 5 verfügbar?

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 von diese Funktionen zu unterstützen.

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

185
Senseful

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

enter image description here

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: [email protected]@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 müssen in einem /** block */, /*! block */ oder vorangestellt mit /// oder //!.
  • Die Befehle arbeiten mit dem @ ( headerdoc style) oder das \ ( doxygen style) Präfix. (D. H. @b und \b beide machen dasselbe.)
  • Die Befehle kommen normalerweise vor dem Gegenstand, den sie beschreiben. (Wenn Sie also versuchen, eine Eigenschaft zu dokumentieren, muss der Kommentar vor dem @property Text.) Sie können danach in der gleichen Zeile kommen, mit /*!<, /**<, //!<, ///<.
  • Sie können die Dokumentation zu Klassen, Funktionen, Eigenschaften, und Variablen hinzufügen.
  • Alle diese Befehle werden in dunkelgrünem Text angezeigt, um anzuzeigen, dass sie gültige Befehle sind, mit Ausnahme von @returns.
  • Möglicherweise müssen Sie Ihr Projekt erstellen (oder Xcode neu starten), bevor die letzten Änderungen an Ihrer Dokumentation angezeigt werden.

Wo finden Sie die Dokumentation:

1. Während der Code vervollständigt wird, sehen Sie den kurzen Text:

enter image description here

Dies zeigt den kurzen Text (ohne Formatierung); Wenn kein kurzer Text vorhanden ist, wird eine Verkettung des gesamten Texts bis zum ersten @Block angezeigt. Wenn keine vorhanden ist (z. B. wenn Sie mit @return beginnen), wird der gesamte Text so zusammengefasst, dass alle @ -Befehle entfernt werden.

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

enter image description here

3. Klicken Sie im Informationsfenster der Schnellhilfe auf

(Siehe erster 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 die Dokumentation 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 keinen Zeilenumbruch. Eine Möglichkeit, eine neue Zeile zu erstellen, besteht darin, sicherzustellen, dass sich in dieser Zeile nichts befindet. Nicht einmal ein Leerzeichen!
  • \example

Die folgenden werden nicht unterstützt (sie werden nicht einmal dunkelgrün angezeigt):

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

Reservierte Schlüsselwörter von Apple:

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

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

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

Das Schlüsselwort verursacht bestenfalls 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).

416
Senseful

Swift 2. verwendet die folgende Syntax:

/**
        Squares a number.

        - parameter parameterName: number The number to square.

        - returns: The number squared.
    */

Beachte wie @param ist jetzt - parameter.

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

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

Sinnvoll:

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

Manchmal hat mir das nicht gereicht. Wenn Sie Xcode schließen und das Projekt sichern, werden diese Fälle in der Regel behoben.

Ich erhalte auch unterschiedliche Ergebnisse in H-Dateien und M-Dateien. Ich kann keine neuen Zeilen abrufen, wenn sich die Dokumentationskommentare in einer Headerdatei befinden.

9
weezma2004

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

anstelle von :param: thing description of thing (wie in Swift 1.2)

es ist jetzt - parameter thing: description of thing

Die meisten der Schlüsselwörter wurden durch - [keyword]: [description] Anstelle von :[keyword]: [description] Ersetzt. Derzeit enthält die Liste der Keywords, die nicht funktionieren, abstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, related, ref.

5
mittens