Automatic ké generovanie metrík a dokumentácie zo zdrojových kódov

Martin Sirota FIIT STU Bratislava, 10. jún 2008 Automatické generovanie metrík a dokumentácie zo zdrojových kódov

Obsah • Zadanie projektu • Predstavenie existujúcich riešení • Predstavenie LuaDoc • Riešenie projektu • Prínosy projektu • Porovnanie projektu

Zadanie projektu • Automatické generovanie dokumentácie • Jazyk Lua • Zamerať sa na dve hlavné funkcie: • Používateľsky definované značky (tagy) • Farebne zvýraznený zdrojový kód v dokumentácii

Predstavenie existujúcich riešení • Všetky riešenia pracujú na princípe komentárov • Špeciálna syntax a špeciálne značky --- Define special sequences of characters. -- For each pair (find, subs), the function will create a field -- find which has the value of subs. -- It also creates an index for the table -- @param subs The replacement pattern. -- @param find The pattern to find. -- @returnescapecharacters table functiondef_escapes (find, subs) local special = { t = "\t", n = "\n", ['"'] = '"', ['\\'] = '\\', } find = gsub (find, "\\(.)", function (x) return %special[x] or x end) subs = gsub (subs, "\\(.)", function (x) return %special[x] or x end) escape_sequences.n = escape_sequences.n+1 escape_sequences[escape_sequences.n] = find escape_sequences[find] = subs returnspecial end

Predstavenie existujúcich riešení – pokr. • Doxygen • Najznámejší, najpoužívanejší • Veľké množstvo možností a nastavení • Až 137 rôznych značiek • Podporuje rôznu syntax komentárov • Javadoc • Súčasť balíka J2SE • Priama podpora v mnohých Java IDE

Predstavenie existujúcich riešení – pokr. • Lua • Žiadna podpora od veľkých projektov • LuaDoc • Najznámejší, najpoužívanejší, najpokročilejší • Flexibilná architektúra • ExpLua • Experimentálny projekt • Zaujímavá syntax • Stdlib • Veľmi jednoduchá podpora na parsovanie komentárov • Tvorba jednoduchých HTML súborov

.lua súbory .html files dokumentácia taglet doclet Predstavenie LuaDoc • 11 značiek, bez možnosti modifikácie • XHTML výstup

Riešenie projektu • Použitie LuaDoc ako základ pre modifikácie • Používateľsky definované značky • Úprava štandardného tagletu • Konfiguračný súbor • Farebne zvýraznený zdrojový kód v dokumentácii • Knižnica na parsovanie/dumpovanie zdrojových kódov • Cheese, LuaFish • Úprava štandardného (HTML) dockletu

LuaFishparser LuaFishdumper tagfile .html files .luafiles dokumentácia taglet doclet Riešenie projektu– pokračovanie

Prínosy projektu • Interoperabilita s ostatnými projektmi • Možnosť používania vlastného jazyka --% Opis funkcie --- Druhý riadok opisu funkcie --- Tretí riadok opisu funkcie --@ first (string) Popis prvého parametra --@ what (table) Popis druhého parametra --- druhý riadok popisu druhého parametra --@ [...] (any) Voliteľný parameter --: (number) Popis návratovej hodnoty funkcie functionModule:MyFunction( first, what, ... ) ... end

Prínosy projektu – pokr. • Zdrojové kódy v dokumentácii • Formátovanie je nezávislé od „čistoty“ kódu • Farebne zvýraznenie – lepšia čitateľnosť • Zdrojový kód celého súboru

Porovnanie projektu • Vlastné značky a zvýraznený zdrojový kód – jedinečné funkcie v rámci Lua

Ďakujem za pozornosť

Automatic ké generovanie metrík a dokumentácie zo zdrojových kódov