Jazzy srovná dokumentaci do latě

14. 5. 2019 Lukáš Šanda

Ve světě vývojářů se říká, že nějaká dokumentace je lepší než žádná dokumentace. To je sice pravda, ale i tak nás při práci s ní může čekat spoustu nepříjemností. Proto existuje nástroj Jazzy, který umí dokumentaci vygenerovat pomocí jediného příkazu. Pomáhá tak efektivněji využít náš čas a nenutí nás zdlouhavě „překládat” kód pro ty, kdo se v něm teprve chtějí zorientovat. Pojďme se podívat, jak tahle užitečná věc funguje.

Varování: Následující zpráva je noční můrou každého vývojáře!

Čeká nás několikahodinové procházení stovek řádků kódu, než zjistíme, k čemu vlastně onen nástroj slouží. S pomocí Jazzy takové situaci můžeme předejít. Usnadníme tím práci člověku, který bude v budoucnu naše řešení implementovat. Navíc není nutné si vyhrazovat extra čas na sepisování externí dokumentace k 3rd party frameworku.

O co jde

Jazzy je nástroj pro platformu iOS. Vychází z dokumentačních komentářů, tzv. DocString, napříč zdrojovým kódem a vytváří z nich dokumentaci. Velkou výhodou je, že tento formát odpovídá tzv. Quick Help Documentation formátu. Pro vytvoření zmíněných komentářů lze použít klávesovou zkratku Command + Control + /, čímž vygenerujeme základní strukturu, kterou můžeme doplnit o další informace.

Komentování zdrojových kódů k vývoji standardně patří, takže vývojáře nezatěžujeme dalšími zbytečnými úkony. Pokud máme správně dokumentovaný kód, z terminálového prostředí zadáme klíčové slovo jazzy a vygeneruje se nám dokumentace podle výchozího nastavení.

Generování pomocí ACL

Pokud vytváříme nějakou knihovnu či framework, definujeme rozhraní, se kterým budou vývojáři pracovat. V takovém případě je projekt rozdělen na veřejnou a neveřejnou část. Veřejná část musí být samozřejmě plně zdokumentována. Ale co ta neveřejná? Komentovat či nekomentovat? To už je na rozvaze samotného týmu. Pokud předpokládáme, že bude náš framework dále vyvíjen někým jiným, je záhodno přidat komentáře i pro původně neveřejné funkce a proměnné.

Ve výchozím stavu generuje Jazzy dokumentaci pro ACL (Access Control Layer) public a vyšší. Při generování, které se provádí v terminálu pomocí příkazu jazzy, můžeme specifikovat úroveň ACL, pro kterou dokumentaci vytváříme. Pokud chceme dokumentaci i pro privátní prvky, přidáme k příkazu jazzy –min-acl private.

Struktura dokumentace a výstupní formáty

Ve výchozím stavu má dokumentace strukturu podle modifikátorů objektů, tj. Classes, Structures, Enums, Protocols aj. Avšak je možné vytvořit si i vlastní strukturu. Například pokud vytváříme knihovnu s UI komponenty a chceme mít strukturu s vlastními Buttons či Labels. Výstup je možné vygenerovat ve třech možných formátech – Apple, Jony a Fullwidth. Apple je výchozí formát. Dokumentace ve výchozím stavu vypadá následovně: