Über einfaches Markdown in DocC hinaus
Die meisten Entwickler wissen, dass DocC Standard-Markdown unterstützt, aber es gibt zwei mächtige Direktiven, die überraschend wenig genutzt werden: Video-Einbettung und Tab-Inhalte. Beide funktionieren in Xcodes Dokumentations-Viewer und auf gehosteten DocC-Websites.
Videos einbetten
Ein Video zur Dokumentation hinzuzufügen ist eine einzige Direktive:
@Video(source: "setup-walkthrough.mp4")Platziere die Videodatei im Resources-Ordner deines Dokumentationskatalogs. Das rendert einen Inline-Videoplayer direkt in der Dokumentation, was weitaus effektiver ist als auf eine externe URL zu verlinken oder einen visuellen Prozess in Text zu beschreiben. Es funktioniert gut für Setup-Guides, UI-Walkthroughs oder das Demonstrieren von Animationen.
Tab-Inhalte mit TabNavigator
Wenn du alternative Ansätze oder plattformspezifische Anleitungen zeigen musst, halten Tabs die Dinge übersichtlich, ohne den Leser zu überfordern:
@TabNavigator {
@Tab("SwiftUI") {
Use the `.environment` modifier to inject dependencies.
}
@Tab("UIKit") {
Override `viewDidLoad` and configure your dependencies there.
}
}Das rendert als echtes Tab-Interface, bei dem Leser zwischen Abschnitten wechseln können. Es ist besonders nützlich für Dokumentation, die mehrere Plattformen, API-Versionen oder Konfigurationsansätze abdeckt.
Praktische Hinweise
Ich habe meinen Contributing-Guide aktualisiert, um beide Features zu nutzen, und das Ergebnis ist deutlich zugänglicher als eine Textwand. Das Video zeigt den Setup-Prozess, der Absätze zum Beschreiben brauchen würde, und die Tabs trennen plattformspezifische Schritte sauber.
Diese Direktiven sind in Apples DocC-Dokumentation dokumentiert, werden aber selten in Tutorials erwähnt. Wenn du ein Open-Source Swift Package pflegst, überlege, sie deinem Dokumentationskatalog hinzuzufügen – sie machen einen echten Unterschied dabei, wie Leute deine Docs erleben.