Dokumentationsgenerator - ett program eller mjukvarupaket som låter dig få dokumentation avsedd för programmerare ( API- dokumentation ) och/eller för slutanvändare av systemet, enligt en speciellt kommenterad källkod och, i vissa fall, körbara moduler (erhållna på utdata från kompilatorn ).
Vanligtvis analyserar generatorn programmets källkod och lyfter fram de syntaktiska konstruktionerna som motsvarar programmets betydande objekt (typer, klasser och deras medlemmar/egenskaper/metoder, procedurer/funktioner, etc.). Analysen använder också metainformation om programobjekt, presenterad i form av dokumenterande kommentarer. Baserat på all information som samlas in, skapas färdig dokumentation som regel i ett av de allmänt accepterade formaten - HTML , HTMLHelp , PDF , RTF och andra.
En dokumentkommentar är en speciellt formaterad kommentar på ett programobjekt för användning av en specifik dokumentationsgenerator. Syntaxen för de konstruktioner som används i dokumentationskommentarer beror på vilken dokumentationsgenerator som används .
Dokumentationskommentarer kan innehålla information om kodförfattaren, beskriva syftet med programobjektet, betydelsen av in- och utdataparametrar för en funktion/procedur, användningsexempel, möjliga undantag och implementeringsfunktioner.
Dokumentationskommentarer formateras vanligtvis som kommentarer i C -stil med flera rader . I varje fall måste kommentaren komma före det dokumenterade elementet. Det första tecknet i en kommentar (och i början av kommentarsraderna) måste vara *. Blocken separeras med tomma rader.
Ett exempel på en dokumentär kommentar i PHP :
/** * Objektnamn eller kort beskrivning * * Lång beskrivning * * @descriptor_name value * @return data_type */| Lista över phpDocumentor- handtag | ||
|---|---|---|
| Beskrivare | Beskrivning | Exempel |
| @author | Författare | /** * Exempelfil 2, phpDocumentor Snabbstart * * En fil från phpDocumentor-dokumentationen * som visar hur man kommenterar. * @författare Greg Beaver <[email protected]> * @version 1.0 * @package sample * @subpackage classes */ |
| @version | Kodversion | |
| @package | Anger paketet som koden tillhör | |
| @subpackage | Anger ett underpaket | |
| @global | Beskrivning av globala variabler | /** * DocBlock för en global variabel * @globalt heltal $GLOBALS['myvar'] följt av en funktion med en global variabel * eller en global variabel, i vilket fall du måste ange dess namn * @name $myvar */ $ GLOBALS [ 'myvar' ] = 6 ; |
| @name | Namn, etikett | |
| @staticvar | Beskrivning av statiska variabler | /** * @staticvar heltal $staticvar * @return returnerar ett heltalsvärde */ |
| @return | Beskrivning av returvärde | |
| @todo | Anmärkningar för senare implementering. | /** * DocBlock med kapslade listor * @todo Enkel TODO-lista * - item 1 * - item 2 * - item 3 * @todo Nested TODO-lista * <ol> * <li>item 1.0</li> * <li> objekt 2.0</li> * <ol> * <li>objekt 2.1</li> * <li>objekt 2.2</li> * </ol> * <li>objekt 3.0</li> * </ol> */ |
| @link | Länk | /** * Det här är ett exempel på {@link http://www.example.com inbäddad hyperlänk} */ |
| @deprecated (@deprec) | Beskrivning av det föråldrade blocket | /** * @deprecated description * @deprec är en synonym för utfasad */ |
| @example | Exempel | /** * @abstract * @åtkomst offentlig eller privat * @copyright namndatum * @exempel /sökväg/till/exempel * @ignorera * @intern privat information för specialister * @paramtyp [$varname] indataparameterbeskrivning * @return typ returvärdebeskrivning * @se annat elementnamn (referens) * @sedan version eller datum * @statisk */ |
| @see | Länk till annan plats i dokumentationen | |
| Andra beskrivningar | ||
| @copyright • @license • @filesource • @category • @since • @abstract • @access • @example • @ignore • @internal • @static • @throws • @uses • @tutorial | ||
Ett exempel på en dokumentkommentar för en funktion i ett Java -program , avsedd att användas av Javadoc :
/** * Kontrollerar om flytten är giltig. * Till exempel, för att ställa in draget e2-e4, skriv isValidMove(5,2,5,4); * @författare John Doe * @param theFromFile Vertical där formen är placerad (1=a, 8=h) * @param theFromRank Horizontal där formen är (1...8) * @param theToFile Vertikal av cellen där flytta utförs (1=a, 8=h) * @param theToRank Den horisontella cellen som ska flyttas till (1...8) * @return true om flytten är giltig och falsk om den inte är giltig */ boolean isValidMove ( int theFromFile , int theFromRank , int theToFile , int theToRank ) { . . . }Exempel för olika språk och programmeringsmiljöer: