Generator de documentație - un program sau pachet software care vă permite să obțineți documentație destinată programatorilor ( documentația API ) și/sau utilizatorilor finali ai sistemului, conform unui cod sursă special comentat și, în unele cazuri, module executabile (obținute la ieșirea compilatorului ).
De obicei, generatorul analizează codul sursă al programului, evidențiind construcțiile sintactice corespunzătoare obiectelor semnificative ale programului (tipuri, clase și membrii/proprietățile/metodele acestora, proceduri/funcții etc.). Analiza folosește și metainformații despre obiectele programului, prezentate sub formă de comentarii documentare. Pe baza tuturor informațiilor colectate, documentația gata făcută se formează, de regulă, într-unul dintre formatele general acceptate - HTML , HTMLHelp , PDF , RTF și altele.
Un comentariu document este un comentariu special formatat pe un obiect de program pentru a fi utilizat de către un anumit generator de documentație. Sintaxa constructelor utilizate în comentariile documentației depinde de generatorul de documentație utilizat .
Comentariile documentației pot conține informații despre autorul codului, descriu scopul obiectului programului, semnificația parametrilor de intrare și de ieșire pentru o funcție/procedură, exemple de utilizare, posibile excepții și caracteristici de implementare.
Comentariile documentației sunt de obicei formatate ca comentarii în stil C cu mai multe linii . În fiecare caz, comentariul trebuie să apară înaintea elementului documentat. Primul caracter dintr-un comentariu (și la începutul liniilor de comentariu) trebuie să fie *. Blocurile sunt separate prin linii goale.
Un exemplu de comentariu documentar în PHP :
/** * Nume obiect sau descriere scurtă * * Descriere lungă * * @descriptor_name valoare * @return data_type */| Lista de mânere phpDocumentor | ||
|---|---|---|
| Descriptor | Descriere | Exemplu |
| @author | Autor | /** * Exemplu de fișier 2, phpDocumentor Quickstart * * Un fișier din documentația phpDocumentor * care demonstrează cum să comentezi. * @author Greg Beaver <[email protected]> * @version 1.0 * @package sample * @subpackage classs */ |
| @version | Versiunea codului | |
| @package | Specifică pachetul căruia îi aparține codul | |
| @subpackage | Specifică un subpachet | |
| @global | Descrierea variabilelor globale | /** * DocBlock pentru o variabilă globală * @global integer $GLOBALS['myvar'] urmat de o funcție cu o variabilă globală * sau o variabilă globală, caz în care trebuie să specificați numele acesteia * @name $myvar */ $ GLOBALE [ ' myvar ' ] = 6 ; |
| @name | Nume, etichetă | |
| @staticvar | Descrierea variabilelor statice | /** * @staticvar întreg $staticvar * @return returnează o valoare întreagă */ |
| @return | Descrierea valorii returnate | |
| @todo | Note pentru implementare ulterioară. | /** * DocBlock cu liste imbricate * @todo Lista simplă de TODO * - elementul 1 * - elementul 2 * - elementul 3 * @todo Listă imbricată de TODO * <ol> * <li>elementul 1.0</li> * <li> elementul 2.0</li> * <ol> * <li>articolul 2.1</li> * <li>articolul 2.2</li> * </ol> * <li>articolul 3.0</li> * </ol> */ |
| @link | Legătură | /** * Acesta este un exemplu de {@link http://www.example.com hyperlink încorporat} */ |
| @deprecated (@deprec) | Descrierea blocului învechit | /** * @deprecated description * @deprec este un sinonim pentru deprecated */ |
| @example | Exemplu | /** * @abstract * @access public sau privat * @copyright nume data * @example /path/to/example * @ignore * @informații private interne pentru specialiști * @param type [$varname] descriere parametru de intrare * @return tip returnare valoare descriere * @vedeți alt nume de element (referință) * @din versiune sau dată * @static */ |
| @see | Link către un alt loc din documentație | |
| Alți descriptori | ||
| @copyright • @license • @filesource • @category • @since • @abstract • @access • @example • @ignore • @internal • @static • @throws • @uses • @tutorial | ||
Un exemplu de comentariu document pentru o funcție dintr-un program Java , destinat să fie utilizat de Javadoc :
/** * Verifică dacă mutarea este validă. * De exemplu, pentru a seta mutarea e2-e4, scrieți isValidMove(5,2,5,4); * @author John Doe * @param theFromFile Verticala unde este forma (1=a, 8=h) * @param theFromRank Orizontala unde este forma (1...8) * @param theToFile Verticala unde forma se efectuează mutarea (1=a, 8=h) * @param theToRank Orizontală a celulei la care trebuie mutată (1...8) * @return true dacă mutarea este validă și false dacă nu este validă */ boolean isValidMove ( int theFromFile , int theFromRank , int theToFile , int theToRank ) { . . . }Exemple pentru diferite limbi și medii de programare: