Jazzy srovná dokumentaci do latě | eMan

Jazzy srovná dokumentaci do latě

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ě:

Jazzy je užitečný nástroj, který může ušetřit spoustu trápení a nervů. Takže proč si dělat práci zbytečně těžší, když to může být pohoda jazzy?

 

Lukáš Šanda

Lukáš Šanda
Lukáš Šanda
iOS Developer

EMAN EUROPE

eMan s.r.o.
U Pergamenky 1145/12
170 00 Praha 7
Česká republika

Zobrazit na mapě

+420 222 202 222
info@eman.cz

EMAN NORTH AMERICA

eMan Solutions LLC.
Tower Executive Suites
19901 Southwest Fwy
Sugar Land, TX 77479
United States of America
Zobrazit na mapě

+1 (346) 232 2867
hello@emanglobal.com