Evropský sociální fond. 12. Dokumentace zdrojového kódu Tvorba elektronické dokumentace Ing. Ondřej Guth Katedra teoretické informatiky Fakulta informačních technologií České vysoké učení technické v Praze c Ondřej Guth, 2010 LS 2010/2011 (poslední změna 2010/2011) Praha & EU: Investujeme do vaší budoucnosti O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 116 / 159 Obsah přednášky 1 2 ++ Nastavení O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 117 / 159 Co je diagram tříd Unified Modelling Language grafický jazyk pro vizualizaci, specifikaci a dokumentaci SW Object Management Group omg.org více o v jiném předmětu, zde jen částečně diagramy tříd class diagram vlastnosti tříd obsah tříd (atributy, operace) vztahy tříd (dědičnost,... ) O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 118 / 159 O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 119 / 159
Příklad Zdroj Příklad Diagram Vozidlo.java package pkg; public interface Vozidlo { public int pocetkol(); } abstract class MotoroveVozidlo implements Vozidlo { protected int spotreba; public abstract boolean muzetahnout(motorovevozidlo tazene); } class Auto extends MotoroveVozidlo { static class Kolo { } static final int POCET_KOL_AUTA = 4; protected Kolo [] kola; private boolean marezervu; public int pocetkol() { return POCET_KOL_AUTA; } public boolean muzetahnout(motorovevozidlo tazene) { return false; } } O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 120 / 159 O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 121 / 159 Upřesnění Stereotypy Enumeration abstraktní entity kurziva statické podtržení standardně se vynechává označení položky (Attributes, Operations) parametry operací: lze specifikovat směr: + pridej( in co : int, inout zasobnik : Zasobnik ) jmenné prostory a kvalifikování entit atribut spotreba: pkg::motorovevozidlo::spotreba místo ikon u entit označujících rozhraní apod. lze použít stereotypy (např. <<interface>>) doplňující informace k významu ještě např. <<interface>> a mnoho dalších (jaké si vymyslíte) O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 122 / 159 O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 123 / 159
Asociace Asociace Agregace vztah tříd násobnost (multiplicity) pojmenování celé asociace nebo účastníka orientace když jeden účastník neví o druhém implementace, zobecnění, agregace speciální případ asociace O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 124 / 159 vyjadřují skládání kompozice speciální případ agregace oddělení nemůže existovat bez firmy O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 125 / 159 Doxygen Základy systém na dokumentaci zdrojového kódu dokumentuje se speciálními komentáři jednotlivých entit Doxygen umožňuje z komentářů vygenerovat dokumentaci www.doxygen.org podpora mnoha programovacích jazyků (C, C++, Java, PHP, C#, Python a další) několik výstupních formátů (HTML, LATEX, RTF, UNIX man) běží na Linuxu, Windows a dalších systémech je zdarma, šířený pod GNU licencí dokumentovat lze řadu entit programu: zdrojový soubor, třídu, proměnnou, funkci,... TIP: co všechno dokumentovat? pokud možno vše speciální komentář vztažený k některé entitě jednořádkový začínající /// nebo //! blokovy začínající /** nebo /*! vazba komentář entita prostřednictvím umístění (bezprostředně před entitou) stručný a detailní popis: stručný například do seznamu O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 126 / 159 O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 127 / 159
Neokomentovaný Okomentovaný simplefile.c int varia; int main(int argc, char **argv) { return 0; } simplefile.c /// Proměnná. /** Taková proměnná. Co víc k tomu dodat. */ int varia; //! Hlavní funkce. //! Ta nejhlavnější funkce celého programu. //! Dá se to rozepsat na víc řádek. int main(int argc, char **argv) { return 0; } O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 128 / 159 O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 129 / 159 Výsledek Komentář za entitou zasobnik.h /// Prvek zásobníku. /** Datová struktura, kterou je možné vkládat a nebo vyjímat do/ze zásobníku. */ typedef struct { int cislo; //!< Číslo. enum charakter vlastnost; ///<Názor na číslo. } prvek; symbol < hned na začátku komentáře zde pouze stručný popis O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 130 / 159 O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 131 / 159
Značky Komentář za entitou se značkou značka tag upřesnění sémantiky lepší strukturování umožnění umístění komentářů jinam než před entitu formát \značka nebo @značka příklady: \brief stručný popis \param parametr funkce / procedury / metody \returns návratová hodnota funkce / procedury / metody O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 132 / 159 zasobnik.h //! Vnitřní %prvek zásobníku. //! Datová struktura tvořící interně prvky zásobníku. //! Slouží především k odkazování na vrchol zás. typedef struct prvek_zasobniku { struct prvek_zasobniku *dalsi; /*!< \brief Ukazatel na předchozí vnitřní %prvek zásobníku. */ prvek p; //!< Prvek (data) zásobníku. } prvek_zasobniku; Při použití blokového komentáře nutno použít značku brief pro stručný popis. Pro zabránění automatického odkazování lze umístit znak %. O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 133 / 159 se značkami Zdrojový soubor se značkami Komentář daleko od entity výčet zasobnik.h /*! @file zasobnik.h @brief Zásobník. Hlavičkový soubor zásobníku. */ Mezi stručným a podrobným popisem je prázdná řádka. Před stručný popis je třeba umístit značku (blokový komentář). Jediný způsob dokumentace zdrojového souboru je použití značky file. zasobnik.h nahoře /** \enum charakter * \brief Charakter čísla. * * Názor na základní vlastnost čísla. */ zasobnik.h níže enum charakter {velke, male, nepodstatne} charakter; V tomto případě je nutné uvést, co komentujeme: \enum charakter (tedy včetně názvu). Je třeba označit stručný popis značkou. O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 134 / 159 O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 135 / 159
se značkami se značkami zasobnik.h nahoře /*! \fn vloz(prvek_zasobniku **vrchol, prvek p) \brief Vložení prvku na vrchol zásobníku. \param[in,out] vrchol Ukazatel na ukazatel na vrchol zásobníku, předání nového odkazem. \param[in] p Prvek, který se má vložit. Vloží prvek p na vrchol zásobníku daný parametrem vrchol. Prázdný zásobník - vrchol je NULL. */ zasobnik.h níže void vloz(prvek_zasobniku **vrchol, prvek p); Nutno funkci specifikovat více než jen názvem (přetěžování). Víceřád. komentář za zn. (param) stručný a detailní popis. O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 136 / 159 zasobnik.h nahoře /*! \fn vyjmi(prvek_zasobniku **vrchol) \brief Vyjme prvek z vrcholu zásobníku. \param[in,out] vrchol Ukazatel na ukazatel na vrchol zásobníku. Nový ukazatel na vrchol zásobníku je tímto parametrem předán odkazem. \return Vyjmutý prvek z původního vrcholu zás. Vyjme a vrátí prvek z vrcholu zásobníku. Zásobník nesmí být prázdný. */ zasobnik.h níže prvek vyjmi(prvek_zasobniku **vrchol); Typ parametru (vstupní i výstupní). O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 137 / 159 Formátování cislo.h Operace nebude provedena, je-li: - druhý operand nekompatibilní s tímto číslem, - hodnota druhého operandu rovna <em>nule</em>. Formátování Odkazy URL a e-mailové adresy se automaticky převedou identifikátory jsou převedeny na odkazy pokud nezafunguje, lze si pomoci značkou ref identifikátor přidání kapitoly s odkazy ( See also ) značkou sa nečíslovaný seznam s pomocí pomlček, číslovaný seznam s pomocí -#, lze vložit i libovolnou HTML značku (pro ne-html formáty bude převedena). O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 138 / 159 O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 139 / 159
Matematika Další možnosti cislo.h Přinásobí k tomuto číslu operand daný parametrem, výsledek je uložen do tohoto čísla. Výsledkem zavolání této metody na tomto čísle \f$t\f$ s operandem \f$d\f$ je: \f[ t\leftarrow t*d \f] vlastní hlavní stránka: značka mainpage vložení obrázku: značka image pro různé výstupní formáty se zadává zvlášť (html, latex) pro LATEX: eps, pro HTML: png, gif, jpeg konfigurační volba IMAGE_PATH např: \image html logo_cvut.png "Logo ČVUT" Funguje s pomocí L ATEX. O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 140 / 159 O. Guth (FIT ČVUT) BI-TED: 12. Dokumentace zdrojového kódu 141 / 159