Ich verwende Doxygen, um Dokumente für meinen objektiven c-Code zu generieren. Bis jetzt konnte ich jedoch keine Richtlinien finden, wie Eigenschaften richtig zu dokumentieren sind. Beispiele, die ich mir angeschaut habe, machen es auf jede erdenkliche Art und Weise. Einige Leute dokumentieren die Variablen selbst, andere dokumentieren die @property-Deklarationen. Manche benutzen //, während andere volle / ** * / Blöcke benutzen.
Kann jemand mich auf eine Referenz für Best Practices hinweisen? Oder vielleicht ein paar Informationen über die zukünftige Kompatibilität mit Doxygen? Ich würde gerne an einem Muster festhalten, das sich zumindest leicht an Doxygen anpassen lässt, sobald sie ein offizielles Muster entwickelt haben.
Ich kann nur sagen, dass das Core Plot-Framework Eigenschaftsdeklarationen in der Implementierung mit einem Format wie folgt annotiert
%Vor%und es scheint, saubere Dokumentation mit Doxygen zu produzieren. Aus der Core Plot-Dokumentation :
Die @ Eigenschaft wird als Doxygen benötigt kann den Namen der Eigenschaft nicht finden sonst.
Accessor-Eigenschaften wie readonly, kopieren / behalten / zuweisen, und nichtatomare sind automatisch hinzugefügt und sollte nicht auftreten im manuellen Teil der Dokumentation.
Hier finden Sie einige Informationen zur Codierungskonvention für das Ziel-C: Google Objective-C Style Anleitung
Aber wenn Sie wollen, gibt es noch einen anderen guten Soft namens HeaderDoc, um Dokumentation unter XCode zu generieren. Sie können seinen Codierungsstil hier überprüfen: HeaderDoc Tags
Meine Erfahrung ist:
Wenn ich das @property-Tag in den Kommentaren verwende, wird die doxygen-Ausgabe der Eigenschaften wie folgt beschädigt: [ClassName]: [read, write, assign].
Wenn ich das @property-Tag weglasse und stattdessen darauf verlasse, dass doxygen die '@property'-Deklaration im Quelltext direkt unterhalb des Kommentarblocks findet, funktioniert alles.
Im Gegensatz dazu funktioniert @interface gut für Schnittstellen und @protocol funktioniert gut für Protokolle.
In der Vergangenheit hatte ich Doxygen auch bei einigen Protokolldeklarationen "untergehen". Ist Obj-C noch ein Doxygen zweiter Klasse?
Hinweis: Ich benutze den GUI / Wizard auf einem Mac, und Kommentarblöcke verwenden '/ * * !' statt '/ * *'.
Tags und Links objective-c iphone comments doxygen