A kóddokumentáció az a folyamat, amelynek során a programozó dokumentálja a kódot. Ez egy jól ismert kifejezés a mérnökök körében. Ha ezt nem teszik meg, az a kód rossz olvashatóságához és a csapat többi tagjának nehéz karbantartásához vezet.
A kóddokumentáció különbözik a projektdokumentációtól, mivel elsősorban arra irányul, hogyan működik a rendszer, de a két folyamatnak van egy közös vonása – a professzionális eszköz használatának követelményei. Ebben a cikkben áttekintek néhány népszerű eszközt a kóddokumentáció készítéséhez.
LaTex
A LaTeX egy dokumentumkészítő rendszer a magas minőségű gépeléshez. Leggyakrabban közepes és nagyméretű műszaki vagy tudományos dokumentumokhoz használják, de szinte bármilyen publikációs formához használható.
A LaTeX nem szövegszerkesztő! Ehelyett a LaTeX arra ösztönzi a szerzőket, hogy ne aggódjanak túl sokat a dokumentumaik megjelenése miatt, hanem koncentráljanak a megfelelő tartalomra.
A LaTeX egy kiváló minőségű szövegszerkesztő rendszer; olyan funkciókat tartalmaz, amelyeket műszaki és tudományos dokumentációk előállítására terveztek. A LaTeX a tudományos dokumentumok közlésének és közzétételének de facto szabványa. A LaTeX szabad szoftverként érhető el.
A LaTeX használatáért nem kell fizetni, ill, nincsenek licencdíjak stb.
Pandoc
A Pandoc számos hasznos markdown szintaxis-kiterjesztést ért, beleértve a dokumentum metaadatait (cím, szerző, dátum); lábjegyzeteket; táblázatokat; definíciós listákat; felső és alsó indexet; áthúzást; bővített rendezett listákat (a kezdőszám és a számozási stílus jelentősége); futó példalistákat; szintaxis-kiemeléssel ellátott körülhatárolt kódblokkokat; intelligens idézőjeleket, kötőjeleket és ellipsziseket; markdown HTML blokkokon belül; és inline LaTeX. Ha szigorú markdown-kompatibilitásra vágyunk, mindezek a bővítmények kikapcsolhatók.
A Pandoc sokféleképpen testre szabható, beleértve egy sablonrendszert és egy hatékony rendszert a szűrők írásához.
A Pandoc tartalmaz egy Haskell könyvtárat és egy önálló parancssoros programot. A könyvtár minden egyes bemeneti és kimeneti formátumhoz külön modulokat tartalmaz, így egy új bemeneti vagy kimeneti formátum hozzáadása csak egy új modul hozzáadását igényli.
A Pandoc szabad szoftver, a GPL alatt jelent meg.
Markdown
A Markdown egy szövegből HTML-be konvertáló eszköz webes írók számára. A Markdown lehetővé teszi, hogy egy könnyen olvasható, könnyen írható egyszerű szöveges formátumban írjon, majd azt szerkezetileg érvényes XHTML (vagy HTML) formátumba konvertálja.
A Markdown formázási szintaxisának legfőbb tervezési célja, hogy a lehető legolvashatóbb legyen. Az elképzelés az, hogy egy Markdown-formázott dokumentumot úgy kell közzétenni, ahogy van, egyszerű szövegként, anélkül, hogy úgy nézne ki, mintha címkékkel vagy formázási utasításokkal lett volna megjelölve. Bár a Markdown szintaxisára számos létező text-to-HTML szűrő hatott, a Markdown szintaxisának legnagyobb inspirációs forrása a sima szöveges e-mailek formátuma.”
LiveEdu
A LiveEdu lehetővé teszi a kóddokumentáció közvetítését és “videokóddokumentáció” létrehozását.”
Az Education Ecosystem egy decentralizált tanulási ökoszisztéma, amely szakembereket és egyetemi hallgatókat tanít arra, hogyan építsenek valódi termékeket. Termékünket a Pluralsight és a Twitch hibridjeként jellemezhetjük. A világ legnagyobb tanulási ökoszisztémáját építjük olyan jövőbeli technológiai témákhoz, mint a mesterséges intelligencia, kiberbiztonság, játékfejlesztés, adattudomány, kriptovaluták és programozás. Az oktatási ökoszisztéma videóalapú, és minden projekt videókat, strukturált projektvázlatot, projektrepót és letölthető forrásokat tartalmaz. A felhasználók klónozhatják a projekt erőforrásokat az Education Ecosystem Git-ről, és futtathatják az alkalmazásokat a helyi gépükön.
Sphinx
A Georg Brandl által írt, BSD licenc alatt álló, intelligens és szép dokumentáció készítését megkönnyítő eszköz.
Eredetileg a Python dokumentációhoz készült, és kiváló lehetőségekkel rendelkezik a szoftverprojektek dokumentálásához számos nyelven. Íme néhány jellemzője:
- Kimeneti formátumok: HTML (beleértve a Windows HTML súgóját), LaTeX (nyomtatható PDF verziókhoz), ePub, Texinfo, kézikönyvoldalak, sima szöveg.
- Kiterjedt kereszthivatkozások: szemantikus jelölés és automatikus hivatkozások függvényekhez, osztályokhoz, hivatkozásokhoz, glosszáriumi kifejezésekhez és hasonló információkhoz.
- Hierarchikus szerkezet: a dokumentumfa egyszerű meghatározása, automatikus hivatkozásokkal a testvérekre, szülőkre és gyermekekre.