Dokumentationsgenerator - et program eller en softwarepakke, der giver dig mulighed for at få dokumentation beregnet til programmører ( API -dokumentation ) og/eller til slutbrugere af systemet i henhold til en specielt kommenteret kildekode og i nogle tilfælde eksekverbare moduler (opnået på output fra compileren ).
Normalt analyserer generatoren programmets kildekode og fremhæver de syntaktiske konstruktioner svarende til programmets væsentlige objekter (typer, klasser og deres medlemmer/egenskaber/metoder, procedurer/funktioner osv.). Analysen anvender også metainformation om programobjekter, præsenteret i form af dokumenterende kommentarer. Baseret på alle de indsamlede oplysninger dannes der som regel færdig dokumentation i et af de almindeligt accepterede formater - HTML , HTMLHelp , PDF , RTF og andre.
En doc-kommentar er en specielt formateret kommentar til et programobjekt til brug for en specifik dokumentationsgenerator. Syntaksen for de konstruktioner, der bruges i dokumentationskommentarer, afhænger af, hvilken dokumentationsgenerator, der bruges .
Dokumentationskommentarer kan indeholde information om kodeforfatteren, beskrive formålet med programobjektet, betydningen af input- og outputparametre for en funktion/procedure, brugseksempler, mulige undtagelser og implementeringsfunktioner.
Dokumentationskommentarer er normalt formateret som kommentarer i C -stil med flere linjer . Kommentaren skal i hvert tilfælde komme før det dokumenterede element. Det første tegn i en kommentar (og i begyndelsen af kommentarlinjerne) skal være *. Blokke er adskilt af tomme linjer.
Et eksempel på en dokumentarkommentar i PHP :
/** * Objektnavn eller kort beskrivelse * * Lang beskrivelse * * @descriptor_name value * @return data_type */| Liste over phpDocumentor- håndtag | ||
|---|---|---|
| Deskriptor | Beskrivelse | Eksempel |
| @author | Forfatter | /** * Eksempelfil 2, phpDocumentor Quickstart * * En fil fra phpDocumentor-dokumentationen *, der viser, hvordan man kommenterer. * @forfatter Greg Beaver <[email protected]> * @version 1.0 * @pakkeeksempel * @underpakkeklasser */ |
| @version | Kode version | |
| @package | Angiver den pakke, som koden tilhører | |
| @subpackage | Angiver en underpakke | |
| @global | Beskrivelse af globale variabler | /** * DocBlock for en global variabel * @global heltal $GLOBALS['myvar'] efterfulgt af en funktion med en global variabel * eller en global variabel, i hvilket tilfælde du skal angive dens navn * @name $myvar */ $ GLOBALS [ 'myvar' ] = 6 ; |
| @name | Navn, etiket | |
| @staticvar | Beskrivelse af statiske variable | /** * @staticvar heltal $staticvar * @return returnerer en heltalsværdi */ |
| @return | Beskrivelse af returværdi | |
| @todo | Noter til senere implementering. | /** * DocBlock med indlejrede lister * @todo Simple TODO-liste * - item 1 * - item 2 * - item 3 * @todo Nested TODO-liste * <ol> * <li>item 1.0</li> * <li> item 2.0</li> * <ol> * <li>emne 2.1</li> * <li>emne 2.2</li> * </ol> * <li>emne 3.0</li> * </ol> */ |
| @link | Link | /** * Dette er et eksempel på {@link http://www.example.com indlejret hyperlink} */ |
| @deprecated (@deprec) | Beskrivelse af den forældede blok | /** * @deprecated description * @deprec er et synonym for forældet */ |
| @example | Eksempel | /** * @abstract * @adgang offentlig eller privat * @copyright navn dato * @eksempel /sti/til/eksempel * @ignorer * @intern privat information for specialister * @param type [$varname] input parameterbeskrivelse * @return skriv returværdibeskrivelse * @se andet elementnavn (reference) * @siden version eller dato * @statisk */ |
| @see | Link til et andet sted i dokumentationen | |
| Andre beskrivelser | ||
| @copyright • @license • @filesource • @category • @since • @abstract • @access • @example • @ignore • @internal • @static • @throws • @uses • @tutorial | ||
Et eksempel på en doc-kommentar til en funktion i et Java -program , beregnet til at blive brugt af Javadoc :
/** * Tjekker om træk er gyldigt. * For eksempel, for at indstille træk e2-e4, skriv isValidMove(5,2,5,4); * @author John Doe * @param theFromFile Den lodrette hvor formen er (1=a, 8=h) * @param theFromRank Den vandrette hvor formen er (1...8) * @param theToFile Den lodrette hvor formen flytningen udføres (1=a, 8=h) * @param theToRank Den vandrette celle, der skal flyttes til (1...8) * @return true, hvis flytningen er gyldig og falsk, hvis den ikke er gyldig */ boolean isValidMove ( int theFromFile , int theFromRank , int theToFile , int theToRank ) { . . . }Eksempler til forskellige sprog og programmeringsmiljøer: