appledoc

Über Appledoc

WICHTIGER HINWEIS: Mitarbeiter gesucht

appledoc ist ein Befehlszeilentool, das Objective-C-Entwicklern hilft, Apple-ähnliche Quellcodedokumentation aus speziell formatierten Quellcodekommentaren zu erstellen. Es ist darauf ausgelegt, möglichst lesbare Quellcodekommentare für die Eingabe zu verwenden und Kommentare sowie den umgebenden Quellcode zu verwenden, um eine optisch ansprechende Dokumentation in Form von HTML sowie einen vollständig indizierten und durchsuchbaren Xcode-Dokumentationssatz zu generieren. Obwohl es mehrere Tools gibt, die HTML-Dokumentation für Objective-C erstellen können, erreichen alle mir bekannten Tools nicht die unten beschriebenen Mindestziele.

Hauptziele von Appledoc:

• Für Menschen lesbare Quellcodekommentare.
• Einfache Querverweise auf Objekte und Mitglieder.
• Generieren Sie eine Apple-ähnliche Quellcode-HTML-Dokumentation.
• Generieren und installieren Sie einen vollständig indizierten und durchsuchbaren Xcode-Dokumentationssatz.
• Ein einziges Tool, um die Generierung vom Parsen des Quellcodes bis zur Installation des Dokumentationssatzes voranzutreiben.
• Leicht anpassbare Ausgabe.
• 100 % Objective-C-Implementierung für einfaches Debuggen.

Um Ihre Erfahrung mit Appledoc so reibungslos wie möglich zu gestalten, empfehlen wir Ihnen dringend, dieses gesamte Dokument sowie die gesamte Online-Dokumentation zu lesen, die im Abschnitt „Appledoc verwenden“ weiter unten erwähnt wird!

Die Nutzung von Appledoc ist gemäß den im Abschnitt „LIZENZ“ am Ende dieser Datei aufgeführten Bedingungen gestattet!

Möchten Sie auf dem Laufenden bleiben? Folgen Sie uns auf Twitter – @gentlebytes.

Schnelle Installation

Die empfohlene Methode besteht darin, das GitHub-Projekt zu klonen und das Tool aus Xcode zu kompilieren. Da durch das Klonen eines GitHub-Projekts die Verbindung zum Haupt-Repository erstellt wird, vereinfacht es auch zukünftige Upgrades erheblich. Geben Sie zur Installation Folgendes in das Terminal ein:

 git clone git://github.com/tomaz/appledoc.git

Dadurch wird das Appledoc-Verzeichnis erstellt. Darin finden Sie den Xcode-Arbeitsbereich appledoc.xcworkspace. Öffnen Sie es und kompilieren Sie das Appledoc-Ziel – dies sollte sofort funktionieren, Ihr System muss jedoch die Mindestsystemanforderungen erfüllen, siehe unten. Ich empfehle Ihnen, die resultierende ausführbare Appledoc-Datei aus dem Build-Verzeichnis in eines der Verzeichnisse in Ihrem Pfad ( echo $PATH ) zu kopieren, um den Zugriff darauf zu erleichtern.

Optional: Appledoc ist eigenständig und enthält die notwendigen Vorlagendateien. WENN Sie diese Standardeinstellungen aus dem Unterverzeichnis „Vorlagen“ an einen der erwarteten Speicherorte ändern möchten:

• ~/Library/Application Support/appledoc
• ~/.appledoc

Sie können auch das Skript install-appledoc.sh verwenden, um eine schnelle Installation durchzuführen. Öffnen Sie Terminal und wechseln Sie in das Appledoc-Verzeichnis. Geben Sie folgenden Befehl ein:

 sudo sh install-appledoc.sh (if you need templates add '-t default')

Es kompiliert Appledoc und installiert seine Binärdatei standardmäßig in /usr/local/bin und Vorlagen (falls gewünscht) in ~/.appledoc. Sie können diese Verzeichnisse mit den Optionen -b bzw. -t überschreiben. Zum Beispiel:

 sudo sh install-appledoc.sh -b /usr/bin -t ~/Library/Application Support/appledoc

Alternativ mit Homebrew:

 brew install appledoc

Homebrew installiert standardmäßig keine Vorlagen.

Appledoc verwenden

Verwenden Sie appledoc --help , um die Liste aller Befehlszeilenschalter anzuzeigen. Weitere Informationen zu Appledoc finden Sie auf der Appledoc-Website. Lesen Sie auch die Wiki-Seiten für einige ausführlichere Artikel.

Nutzen Sie die Appledoc-Google-Gruppe als Forum für Fragen zur Nutzung oder andere allgemeine Fragen.

Verwenden Sie die Appledoc-Problemseite, um Fehler- und Funktionsanfragen einzureichen. Bevor Sie neue Probleme einreichen, überprüfen Sie die Foren, um zu sehen, ob Ihre Frage dort beantwortet wird. Sofern Sie Ihr Problem nicht als eine neue Funktionsanfrage oder einen Fehler bestätigen können, sollten Sie im Forum beginnen, um GitHub-Probleme sauber zu halten. Lesen Sie auch die Ausgaben durch, um zu sehen, ob die Ausgabe bereits vorhanden ist, und stimmen Sie darüber ab oder fügen Sie einen Kommentar hinzu (vergessen Sie nicht die geschlossenen Ausgaben).

Installationstipps

Um auf dem neuesten Stand zu bleiben, gehen Sie einfach zum Terminal und wechseln Sie in das Appledoc-Verzeichnis, geben Sie git pull ein und kompilieren Sie appledoc.xcodeproj neu. Vergessen Sie nicht, die ausführbare Appledoc-Datei zu überschreiben, die Sie nach $PATH kopiert haben :)

Wenn Sie auch das AppledocTests-Ziel (Komponententests) kompilieren und ausführen möchten, müssen Sie alle in der Gruppe „Bibliotheken und Frameworks“ angegebenen Frameworks in das Verzeichnis „Shared Frameworks“ kopieren, bevor Sie das Ziel für Komponententests erstellen! Dies ist für die Erstellung des Appledoc-Tools selbst nicht erforderlich.

Integration mit Xcode

Sie können Xcode so einrichten, dass die Erstellung von Appledoc-Dokumenten automatisiert wird. Erfahren Sie, wie Sie ein Ausführungsskript und die Build-Phasen Ihres Projekts verwenden.

Tipps zur Verwendung von Docsets

Vorgenerierte Dokumentationen und Dokumentationssätze für die meisten Cocoa-Frameworks sind verfügbar unter:

• CocoaDocs

Sobald Sie über einen Dokumentensatz verfügen, möchten Sie ihn möglicherweise mit einem Dokumentationsbrowser verwenden:

• Xcode
• Bindestrich

Fehlerbehebung

Haben Sie Probleme? Folgendes können Sie zur Fehlerbehebung tun:

1. Stellen Sie sicher, dass Sie über die neueste Appledoc-Version verfügen. Versuchen Sie es git pull und führen Sie es erneut mit der neuesten Version aus.
2. Wenn Sie Vorlagendateien installiert haben, stellen Sie sicher, dass Sie die neueste Version verwenden. Löschen Sie die vordefinierten Ordner und lassen Sie Appledoc die Dateien erneut aus dem eingebetteten Archiv kopieren (siehe Abschnitt „Schnellinstallation“ oben).
3. Erhöhen Sie die Ausführlichkeit mit dem Befehlszeilenschalter --verbose . Die Standardstufe ist 2, Sie können die Ausführlichkeit jedoch schrittweise auf bis zu 6 erhöhen, wobei jede Stufe detailliertere Informationen liefert. Da Sie dadurch viel mehr Informationen erhalten, möchten Sie sich möglicherweise nur auf bestimmte Quelldateien konzentrieren, mit denen Sie Probleme haben. Beachten Sie, dass eine zunehmende Ausführlichkeit zu einer langsameren Leistung führt. Daher wird die Verwendung von Stufen über 4 für den täglichen Gebrauch nicht empfohlen.
4. Appledoc ist ein Open-Source-Projekt! Sie haben den gesamten Quellcode zur Verfügung, also führen Sie ihn über Xcode aus. Sie können Xcode so einrichten, dass die gewünschten Befehlszeilenargumente übergeben und Haltepunkte hinzugefügt werden, um Ihr Problem einzugrenzen. Wenn Sie das Gefühl haben, dass Sie mehr zur Community beitragen möchten, können Sie das Projekt gerne auf GitHub forken und ihm Funktionen hinzufügen. Halten Sie uns auf dem Laufenden, damit wir diese Funktionen auch zum Haupt-Repository hinzufügen können – schließen Sie nach Möglichkeit Unit-Tests ein.
5. Wenn Sie der Meinung sind, dass Sie einen Fehler gefunden haben oder eine neue Funktion anfordern möchten, gehen Sie zur Appledoc-Problemseite. Lesen Sie zunächst die vorhandenen Probleme, um festzustellen, ob dort bereits eine Anfrage vorliegt (wenn Sie den Master-Zweig verwenden, lesen Sie auch die geschlossenen Probleme, da Ihre Anfrage möglicherweise bereits abgedeckt wurde, aber noch nicht im Master-Zweig zusammengeführt ist). Sie können über bestehende Anfragen abstimmen, um uns bei der Entscheidung zu helfen, auf welche Funktionen wir uns konzentrieren möchten, oder Sie können einen Kommentar hinzufügen, um bei der Lösung des Problems zu helfen. Wenn Sie die Anfrage dort nicht finden, erstellen Sie ein neues Problem. Fügen Sie nach Möglichkeit Teile von Quelldateien hinzu, die zu Problemen führen, und/oder eine Beschreibung oder Schritte, die dazu führen.
6. Wenn Sie Probleme mit einigen Ihrer Quelldateien haben und diese nicht online veröffentlichen möchten, können Sie uns unten per E-Mail kontaktieren. Wir werden unser Bestes tun, um Ihnen zu helfen, aber bedenken Sie, dass es sich bei Appledoc nicht um ein kommerzielles Produkt handelt; Es wird in unserer Freizeit erstellt und gepflegt, daher sind die Ressourcen begrenzt.

Hinweise des Entwicklers

Wenn Sie einen Beitrag leisten möchten, finden Sie in der Datei „Developer Notes“ einen kurzen Überblick über die interne Funktionsweise von Appledoc.

Mindestsystemanforderungen

• Xcode 4.5 oder höher zum Kompilieren
• OS X 10.7 zum Kompilieren und Ausführen

Lizenz

Appledoc ist mit einer modifizierten BSD-Lizenz lizenziert. Im Klartext: Sie dürfen mit dem Code machen, was Sie wollen, modifizieren, weiterverbreiten oder in Ihre Produkte einbetten (kostenlos oder kommerziell), aber Sie müssen das Urheberrecht, die Nutzungsbedingungen und den Haftungsausschluss wie in der Lizenz angegeben angeben wie jeder andere BSD-lizenzierte Code. Sie können natürlich die von Appledoc generierte Dokumentation für Ihre Produkte verwenden (kostenlos oder kommerziell), aber Sie müssen Appledoc entweder in der Dokumentation selbst oder an einer anderen geeigneten Stelle wie Ihrer Website erwähnen.

Wenn Sie diesen Bedingungen aus irgendeinem Grund nicht zustimmen können, kontaktieren Sie uns über das Kontaktformular auf unserer About-Seite. Wir werden unser Bestes tun, um Ihnen weiterzuhelfen und eine praktikable Lösung zu finden!

Copyright (c) 2009-2011, Gentle Bytes Alle Rechte vorbehalten.

Die Weiterverbreitung und Nutzung in Quell-, Binärform und generierter Dokumentation, mit oder ohne Änderung, ist zulässig, sofern die folgenden Bedingungen erfüllt sind:

• Bei der Weitergabe des Quellcodes müssen der obige Urheberrechtshinweis, diese Liste der Bedingungen und der folgende Haftungsausschluss enthalten sein.

• Bei Weitergaben in binärer Form müssen der obige Urheberrechtshinweis, diese Liste der Bedingungen und der folgende Haftungsausschluss in der Dokumentation und/oder anderen mit der Weitergabe bereitgestellten Materialien wiedergegeben werden.

• Bei der Weiterverbreitung der von Appledoc generierten Dokumentation muss eine Nennung von Appledoc erfolgen, entweder in der Dokumentation selbst oder auf anderen geeigneten Medien.

• Weder der Name des Appledocs, Gentle Bytes noch die Namen seiner Mitwirkenden dürfen ohne vorherige ausdrückliche schriftliche Genehmigung zur Unterstützung oder Werbung für von dieser Software abgeleitete Produkte verwendet werden.

DIESE SOFTWARE WIRD VON DEN COPYRIGHT-INHABERN UND MITARBEITERN „WIE BESEHEN“ ZUR VERFÜGUNG GESTELLT. JEGLICHE AUSDRÜCKLICHE ODER STILLSCHWEIGENDE GEWÄHRLEISTUNGEN, EINSCHLIESSLICH, ABER NICHT BESCHRÄNKT AUF, STILLSCHWEIGENDE GEWÄHRLEISTUNGEN DER MARKTGÄNGIGKEIT UND EIGNUNG FÜR EINEN BESTIMMTEN ZWECK, WERDEN AUSGESCHLOSSEN. IN KEINEM FALL SIND DER COPYRIGHT-INHABER ODER MITARBEITER HAFTBAR FÜR DIREKTE, INDIREKTE, ZUFÄLLIGE, BESONDERE, BEISPIELHAFTE ODER FOLGESCHÄDEN (EINSCHLIESSLICH, ABER NICHT BESCHRÄNKT AUF DIE BESCHAFFUNG VON ERSATZGÜTERN ODER -DIENSTLEISTUNGEN; VERLUSTE VON NUTZUNG, DATEN ODER GEWINNEN); ODER GESCHÄFTSUNTERBRECHUNG) JEDOCH URSACHE UND ÜBER JEGLICHE HAFTUNGSTHEORIE, SEI ES AUS VERTRAG, STRAFHAFTUNG ODER HANDLUNG (EINSCHLIESSLICH FAHRLÄSSIGKEIT ODER ANDERWEITIG), DIE SICH IN IRGENDEINER WEISE AUS DER NUTZUNG DIESER SOFTWARE ERGEBEN, SELBST WENN AUF DIE MÖGLICHKEIT SOLCHER SCHÄDEN HINGEWIESEN WURDE.

Gentle Bytes [email protected]