Dokumentációs generátor - olyan program vagy szoftvercsomag, amely lehetővé teszi a programozóknak ( API dokumentáció ) és/vagy a rendszer végfelhasználóinak szánt dokumentáció beszerzését egy speciálisan kommentált forráskód és bizonyos esetekben végrehajtható modulok (a honlapon beszerezhető) szerint. a fordító kimenete ).
Általában a generátor elemzi a program forráskódját, kiemelve a program jelentős objektumainak megfelelő szintaktikai konstrukciókat (típusok, osztályok és azok tagjai/tulajdonságai/módszerei, eljárások/függvényei stb.). Az elemzés a programobjektumokra vonatkozó metainformációkat is felhasználja, amelyeket dokumentáló megjegyzések formájában mutatnak be. Az összes összegyűjtött információ alapján kész dokumentáció készül, általában az általánosan elfogadott formátumok egyikében - HTML , HTMLHelp , PDF , RTF és mások.
A doc megjegyzés egy speciálisan formázott megjegyzés egy programobjektumhoz, amelyet egy adott dokumentáció-generátor használhat. A dokumentáció megjegyzéseiben használt konstrukciók szintaxisa a használt dokumentációgenerátortól függ .
A dokumentációs megjegyzések tartalmazhatnak információkat a kód szerzőjéről, leírhatják a programobjektum célját, egy funkció/eljárás bemeneti és kimeneti paramétereinek jelentését, használati példákat, lehetséges kivételeket és megvalósítási jellemzőket.
A dokumentációhoz fűzött megjegyzések általában többsoros C -stílusú megjegyzésként vannak formázva . A megjegyzésnek minden esetben a dokumentált elem elé kell kerülnie. A megjegyzésben (és a megjegyzéssorok elején) az első karakternek *. A blokkokat üres sorok választják el.
Példa egy dokumentumfilmes megjegyzésre PHP -ben :
/** * Objektum neve vagy rövid leírása * * Hosszú leírás * * @descriptor_name value * @return data_type */| A phpDocumentor leírók listája | ||
|---|---|---|
| Leíró | Leírás | Példa |
| @author | Szerző | /** * 2. mintafájl, phpDocumentor Quickstart * * Egy fájl a phpDocumentor dokumentációjából *, amely bemutatja a megjegyzések fűzését. * @szerző Greg Beaver <[email protected]> * @version 1.0 * @package sample * @subpackage classes */ |
| @version | Kód verzió | |
| @package | Megadja a csomagot, amelyhez a kód tartozik | |
| @subpackage | Alcsomagot határoz meg | |
| @global | Globális változók leírása | /** * DocBlock globális változóhoz * @global integer $GLOBALS['sajatvar'], majd egy globális változót tartalmazó függvény * vagy egy globális változó, ebben az esetben meg kell adni a nevét * @name $myvar */ $ GLOBÁLOK [ 'myvar ' ] = 6 ; |
| @name | Név, címke | |
| @staticvar | Statikus változók leírása | /** * @staticvar integer $staticvar * @return egész értéket ad vissza */ |
| @return | Visszatérési érték leírása | |
| @todo | Megjegyzések a későbbi megvalósításhoz. | /** * DocBlock beágyazott listákkal * @todo Egyszerű TODO lista * - 1. elem * - 2. elem * - 3. elem * @todo Beágyazott TODO lista * <ol> * <li>1.0 elem</li> * <li> 2.0. tétel</li> * <ol> * <li>2.1. tétel</li> * <li>2.2. tétel</li> * </ol> * <li>3.0. tétel</li> * </ol> */ |
| @link | Link | /** * Ez egy példa a {@link http://www.example.com beágyazott hiperhivatkozásra} */ |
| @deprecated (@deprec) | Az elavult blokk leírása | /** * @deprecated leírás * A @deprec az elavult szó szinonimája */ |
| @example | Példa | /** * @abstract * @access public or private * @copyright name date * @example /elérési út/hoz/példa * @ignore * @belső privát információ a szakemberek számára * @param type [$varname] bemeneti paraméter leírása * @return típus visszatérési érték leírása * @lásd a másik elem nevét (hivatkozás) * @a verzió vagy dátum óta * @static */ |
| @see | Hivatkozás egy másik helyre a dokumentációban | |
| Egyéb leírók | ||
| @copyright • @license • @filesource • @category • @since • @abstract • @access • @example • @ignore • @internal • @static • @throws • @uses • @tutorial | ||
Példa egy doc megjegyzésre egy Java program függvényében , amelyet a Javadoc használ :
/** * Ellenőrzi, hogy a lépés érvényes-e. * Például az e2-e4 mozgás beállításához írja be az isValidMove(5,2,5,4); * @author John Doe * @param theFromFile A függőleges, ahol az alakzat van (1=a, 8=h) * @param theFromRank A vízszintes, ahol az alakzat van (1...8) * @param theToFile A függőleges, ahol az alakzat van az áthelyezés végrehajtásra kerül (1=a, 8=h) * @param theToRank Az áthelyezendő cella vízszintje (1...8) * @return true, ha az áthelyezés érvényes és false, ha nem érvényes */ logikai érték isValidMove ( int theFromFile , int theFromRank , int theToFile , int theToRank ) { . . . }Példák különböző nyelvekre és programozási környezetekre: