Prognyelvek portál

A D programnyelv lehetővé teszi az aktuális kód mellé szerződések, illetve teszt kódok beágyazását is, elősegítve azt, hogy azok konzisztensek maradjanak egymással. Az egyetlen dolog, ami hiányzik, az a dokumentáció, mivel az átlagos kommentek nem alkalmasak arra, hogy automatikusan ki lehessen fejteni, és manual oldalakká lehessen formázni őket. A felhasználói dokumentáció beágyazása a forráskódba nagy előnyökkel jár, például nem kell kétszer leírni a dokumentációt, és valószínűbb, hogy a dokumentáció is konzisztens marad a kóddal.

Néhány létező közelítés ehhez:

Doxygen, ami valamennyire máris támogatja a D-t
A java Javadoc-ja, talán a legismertebb
A C# beágyazott XML-je
Más dokumentációs eszközök

A D céljai a beágyazott dokumentáció készítésére:

Beágyazott dokumentációként is állja meg a helyét, ne csak kicsomagolva és feldolgozva.
Könnyű és magától értetődő legyen megírni, azaz csak minimálisan kelljen pl. <tags>-okban vagy más ügyetlen formulákban megbízni, amik a kész dokumentációban már nem jelennek meg
Ne ismételje azokat az információkat, amiket a fordító már tud a kód elemzéséből
Ne számítson igazán a beágyazott HTML-re, mert ez gátolja a kicsomagolást és a formázást más célokra
Létező D kommentformákon alapuljon, így teljesen független legyen a csak D-re működő elemzőktől
Máshogy nézzen ki, mint a forráskód, nehezen legyen összekeverhető vele, ne legyen zavaró
Tegye lehetővé, hogy a felhasználó Doxygen-t vagy más dokumentáció kezelőt használjon, ha szeretne

Specifikáció

A specifikáció a beágyazott dokumentáció kommentjeinek alakjára csak azt specifikálja, hogy az információ hogy jelenjen meg a fordító számára. Implementációfüggő, hogy az információ hogyan kerül felhasználásra, és hogy milyen lesz a végső prezentáció formája. A végső prezentáció akár egy HTML honlap, man oldal, PDF fájl, stb., ez már nem specifikált része a D programozási nyelvnek.

A feldolgozás fázisai

A beágyazott dokumentáció kommentjei a következő fázisokban kerülnek feldolgozásra:

Lexikális - a dokumentáció kommentjeit felismeri és hozzáadja a tokenekhez
Elemzés - dokumentáció kommentjei összekapcsolódnak a specifikus deklarációkkal és kombinálódnak velük
Szekciók - minden dokumentáció kommentje szekciók szekvenciájára osztódik fel
A speciális szekciók feldolgozásra kerülnek
A nem speciális szekciók kiemelése elkészül
A modul minden szekciója kombinálódik
Makró szöveg cserék hajtódnak végre és elkészítik a végső eredményt.

Lexikális

A beágyazott dokumentáció kommentjei a következő formájúak lehetnek:

/**...*/ A két ** az nyitó / után van
/++...+/ a két ++ nyitó / után van
/// három perjel

A következők mind beágyazott dokumentációk:

/// Ez egy egysoros dokumentáció komment
  
/** Ahogy ez is*/
  
/++ És ez is. +/
  
/**
     Ez egy rövid dokumentáció komment.
*/
   
/**
 * A vezető * ennek a sornak az elején nem része a dokumentáció kommentnek.
*/
   
/**************************
  Az extra *-ok amik rögtön a /**-t követik nem részei a dokumentáció kommentnek
*/
	
/++
 Ez egy rövid dokumentáció komment.
+/
	
/++
  + A vezető + nem része a dokumentáció kommentnek.
+/
  
/++++++++++++++++++++++++++++
  Az extra +-ok amik rögtön a kezdő /++-t követik nem részei a dokumentáció kommentnek.
+/
  
/************************* A záró *-ok szintén nem részei ******************/

Az extra *-ok és +-ok a nyitó és záró kommentekben illetve a kommentek bal szélén nincsenek figyelembe véve, és nem részei a beágyazott dokumentációnak (ld. fenti ábra). Minden olyan komment, ami nem felel meg a fent leírt formáknak, nem dokumentáció komment.

Elemzés

Minden dokumentáció komment össze van kapcsolva a deklarációval. Ha a dokumentáció komment csak egy sor vagy csak whitespace-ek vannak a bal oldalán, akkora következő deklarációra hivatkozik. Többszörös dokumentáció kommentekre ugyan az a deklaráció érvényes, amihez konkatenáltuk. Dokumentáció kommentek nem kapcsolhatók ignorált deklarációhoz. A Modul Deklrációt megelőző dokumenticáió kommentek az egész modulra érvényesek. Ha a dokumentáció kommentek feltűnnek ugyan abban a sorban mint a deklaráció, a deklaráció jobb oldalán, akkor rá vonatkoznak.

Ha a dokumentáció komment csak egy ditto-t (dettó) tartalmaz, akkor az előző deklaráció kommentje érvényes erre is.

Ha nincs a deklarációra dokumentáció komment, akkor az a deklaráció nem lesz benne a kimenetben. Hogy biztosítsuk azt, hogy benne legyen, tegyünk egy üres deklarációs kommentet számára.

int a; //dokumentáció az 'a' részére; b-nek nincs dokumentációja int b; /** dokumentáció c és d részére*/ /** még egy kis dokumentáció c és d részére */ int c; /** ditto */ int d; /**dokumentáció e és f részére */ int e; int f; ///ditto /** dokumentáció g részére */ int g; ///még egy kis dokumentáció g-nek ///dokumentáció C és D-nek class C { int x; /// dokumentáció C.x-nek /** dokumentáció C.y és C.z-nek */ int y; int z; ///ditto } ///ditto class D { }

Szekciók

A dokumentáció kommentek Szekciók sorozatai. Egy Szekció egy név, ami az első nem üres karakter a sorban, amit egy kettőspont (':') követ. Ez a név határozza meg a szekció nevét. A szekció név nem nagybetű érzékeny.

Összegzés (Summary)

Az első szekció az összegzés, neki nincs szekció neve. Ez az első bekezdés, és az első üres sorig vagy a szekció nevéig tart. Bár az összegzés akármilyen hosszú lehet, próbáljuk meg egy soron belül tartani. Az összegzés szekció opcionális.

Leírás (Description)

A következő névtelen szekció a leíró szekció. Ez az összegzést követő összes bekezdést tartalmazza egészen addig, amíg nem találkozunk egy szekció névvel vagy véget nem ér a komment.

A Leírás szekció opcionális, viszont nem állhat leírás szekció összegző szekció nélkül.

/**************************** *Rövid összegzés arról, * hogy a myfunc mit csinál, létrehozva így az összegzés szekciót * * Az első bekezdése az összegzés leírásának * * A második része az összegzés leírásának */ void myfunc() {}

Névvel rendelkező szekciók követik a leíró és az összegző szekciókat.

Hagyományos szekciók

A konzisztencia és kiszámíthatóság érdekében sokféle hagyományos szekció van. Ezek közül egyiknek sem muszáj léteznie.

Szerzők (Authors):

Lista a deklaráció készítőiről.

/** * Authors: Melvin D. Nerd, melvin@mailinator.com */

Bugs (Bugs):

Az ismert bugok listája.

/** * Bugs: Negatív számokra nem működik. */

Dátum (Date):

A jelenlegi kiadás dátuma. A dátum formájának felismerhetőnek kell lennie a std.date számára.

/** * Date: March 14, 2003 */

Érvénytelenített (Deprecated)

Magyarázattal szolgál és megmondja, hogy milyen javítás szükséges, ha a deklaráció amihez hozzáfűztük érvénytelenítve van.

/** * Deprecated: superseded by function bar(). */ deprecated void foo() { ... }

Példák (Examples):

Használható példák

/** * Examples: * -------------------- * writefln("3"); // kiírja a '3'-at a stdout-ra * -------------------- */

Előzmények (History):

Felülvizsgálati előzmények.

/** * History: * V1 kezdeti verzió * * V2 új feature: X */

Licenc (License):

Bármilyen licenc információ a másolásvédett kódhoz.

/** * License: szabadon felhasználható bármilyen célra */ void bar() { ... }

Visszatérés (Returns):

Magyarázat a függvény visszatérési értékéhez. Ha a függvény void, nem szükséges dokumentálni.

/** * Beolvassa a fájlt. * Returns: A fájl tartalmával. */ void[] readFile(char[] filename) { ... }

Lásd még (See_Also):

Más szimbólumok és URL-ek listája, amik ehhez kapcsolódnak.

/** * See_Also: * foo, bar, http://www.digitalmars.com/d/phobos/index.html */

Sztenderd (Standards):

Ha a deklaráció egy bizonyos sztenderdnek felel meg, akkor azt itt lehet leírni.

/** * Standards: Illeszkedik a DSPEC-1234-re */

Dobások (Throws):

Azoknak a kivételeknek a listája, amik kiváltódhatnak, és hogy milyen körülmények között dobódnak.

/** * Írja a fájlt. * Throws: WriteException ha nem sikerül. */ void writeFile(char[] filename) { ... }

Verzió (Version):

Megadja a jelenlegi verzióját a deklarációnak.

/** * Version: 1.6a */

Speciális szekciók

Néhány szekciónak különleges jelentése és szintaktikája van.

Másolásvédelem (Copyright):

Ez tartalmazza a másolásvédelmi felhívást. A COPYRIGHT makró a szekció tartalmára van beállítva amikor dokumentálja a modul deklarációit. A másolásvédelmi szekció csak ezt a speciális eljárást kapja amikor a modult deklaráljuk.

/** Copyright: Public Domain */ module foo;

Paraméterek (Params):

Függvény paramétereket lehet dokumentálni azzal, ha megadjuk őket a paraméterek szekcióban. Minden sor, ami egy azonosítóval és egy "="-el kezdődik, egy új paramétert deklarál. A deklaráció akár több soros is lehet.

/*********************************** * foo does this. * Params: * x = is for this * and not for that * y = is for that */ void foo(int x, int y) { }

Makrók (Macros):

A Makrók szekció szintaktikája megegyezik a Paramétereknek szekcióéval. NAME = érték párok sorozatából áll. A NAME (név) a makró neve, az érték helyére írhatjuk a szöveget.

/** * Macros: * FOO = now is the time for * all good men * BAR = bar * MAGENTA = <font color=magenta></font> */

Kiemelés (Highlighting)

Beágyazott kommentek

A dokumentáció kommentek maguk is kommentezhetőek a $(DDOC_COMMENT komment szöveg) szintaktikával. Ezek a kommentek nem ágyazódnak be.

Beágyazott kód

D kódot is be lehet ágyazni olyan sorokkal, amik legalább három kötőjelet tartalmaznak, és körülhatárolják a kódrészletet.

/++++++++++++++++++++++++ + Saját függvény. + Példa: + -------------------------- + import std.stdio; + + void foo() + { + writefln("foo!"); /* kiírja a stringet */ + } + -------------------------- +/

Vegyük észre, hogy a dokumentáció komment /++...+/-et használ, így a /*...*/ használható a kód szekcióban.

Beágyazott HTML

HTML is beágyazható a dokumentáció kommentekbe, ami változtatás nélkül kerül a HTML kimenetre. Ezzel együtt, mivel nem szükségszerűen HTML lesz a kívánt kimeneti formája a beágyazott dokumentáció kiértékelőjének, ezért a legjobb, ha elkerüljük a használatát ott, ahol ez megoldható.

/** Példa a beágyazott HTML-re:
*   
*  Digital Mars  
*  Empire  * 

*/

Hangsúly (Emphasis)

Az azonosítók a dokumentáció kommentekben, amik függvény paraméterek, vagy hatókörbeli nevek, amik össze vannak kapcsolva a deklarációval, ki vannak emelve a kimenetben. Ez a kiemelés lehet italics, boldface, hyperlink, stb. formájú. Az, hogy hogyan van kiemelve, attól függ, mit emelünk ki - függvény paramétert, típust, D kulcsszót, stb. Hogy megelőzzük a nem szándékos kiemelést, megelőzhetjük egy aláhúzással (_). Az aláhúzás ki lesz húzva a kimenetből.

Karakter entitások

Néhány karakternek speciális jelentése van a dokumentáció feldolgozója számára, ezért hogy ne legyen kavarodás, a legjobb ezeket a megfelelő karakter entitásokkal helyettesíteni:

Karakterek és Entitások

<	<
>	>
&	&

A kód szekcióban ezeket a cseréket nem szükséges elvégezni, vagy ha a speciális karaktert nem követi rögtön a # betű.

Makrók (Macros)

A dokumentáció komment feldolgozó tartalmaz egy egyszerű makró szöveg előfeldolgozót. Amikor a $(NAME) feltűnik a szekció szövegében, akkor ez beírja a megfelelő helyettesítő szöveget a NAME helyére. A helyettesítő szöveget ez után rekurzívan átvizsgálja, hogy tartalmaz-e még makrót. Ha a makró rekurzív kifejtése összeakad, argumentum nélkül vagy ugyan azzal az argumentummal, mint az őt tartalmazó makró, akkor szöveg nélkül cserélődik ki. Azok a makró hívások, amik túlnyúlnak a helyettesítő szöveg határain, nem lesznek kifejtve. Ha a makró neve nem definiált, a helyettesítő szövegben nincsenek karakterek. Ha egy $(NAME) szövegnek léteznie kell a kimenetben anélkül, hogy a makró kifejtené, akkor a $ helyett $ -ot kell írni.

A makróknak lehetnek argumentumaik. Bármilyen szöveg az azonosító végétől a bezáró ')'-ig a $0 argumentum. A $0 a helyettesítő szövegben az argumentum szövegével lesz helyettesítve. Ha vesszők vannak az argumentum szövegben, $1 fogja reprezentálni az argument szöveget az első vesszőig, $2 az első vesszőtől a másodikig, stb., egészen a $9-ig. $+ reprezentálja a szöveget az első vesszőtől a záró ')'-ig. Az argumentum szöveg tartalmazhat beágyazott zárójeleket, "" vagy " stringeket, kommenteket vagy tagokat. Ha alkalmi, nem beágyazott zárójeleket használunk, a ( helyettesíthető a $#40; entitással, a ) pedig a &)-el.

Makró definíciók a következő forrásokból származhatnak, ebben a sorrendben:

1, Előre definiált makrók
2, Definíciók egy meghatározott fájlból a sc.ini vagy dmd.conf DDOCFILE beállítással
3, Definíciók a *.ddoc fájlokból, amiket a parancssorban adunk meg
4, Futás idejű definíciók, amiket a Ddoc generál
5, Definíciók bármelyik Macros: szekcióból

A makró újradefiniálások felülírják az előző azonos nevű definíciókat. Ez azt jelenti, hogy a különböző forrásokból származó makró definíciók sora hierarchiába rendeződik.

A "D_" vagy "DDOC_" -val kezdődő makró nevek foglaltak.

Előre definiált makrók

Ezek bedrótozottak a Ddocba, és azokat a minimális definíciókat reprezentálják, amik a Ddoc formátumnak kellenek, hogy kiemeljék a prezentációt. A definíciók sima HTML számára vannak.

B =	<b>$0</b>
I =	<i>$0</i>
U =	<u>$0</u>
P =	<p>$0</p>
DL = <dl>$0</dl>
DT = <dt>$0</dt>
DD = <dd>$0</dd>
TABLE =	<table>$0</table>
TR = <tr>$0</tr>
TH = <th>$0</th>
TD = <td>$0</td>
OL = <ol>$0</ol>
UL = <ul>$0</ul>
LI = <li>$0</li>
BIG = <big>$0</big>
SMALL =	<small>$0</small>
BR = <br>
LINK = <a href="$0">$0</a>
LINK2 = <a href="$1">$+</a>

RED =   <font color=red>$0</font>
BLUE =  <font color=blue>$0</font>
GREEN = <font color=green>$0</font>
YELLOW =<font color=yellow>$0</font>
BLACK =	<font color=black>$0</font>
WHITE =	<font color=white>$0</font>

D_CODE = <pre class="d_code">$0</pre>
D_COMMENT = $(GREEN $0)
D_STRING  = $(RED $0)
D_KEYWORD = $(BLUE $0)
D_PSYMBOL = $(U $0)
D_PARAM	  = $(I $0)

DDOC = <html><head>
	<META http-equiv="content-type" content="text/html; charset=utf-8">
	<title>$(TITLE)</title>
	</head><body>
	<h1>$(TITLE)</h1>
	$(BODY)
	</body></html>

DDOC_COMMENT   = <!-- $0 -->
DDOC_DECL      = $(DT $(BIG $0))
DDOC_DECL_DD   = $(DD $0)
DDOC_DITTO     = $(BR)$0
DDOC_SECTIONS  = $0
DDOC_SUMMARY   = $0$(BR)$(BR)
DDOC_DESCRIPTION = $0$(BR)$(BR)
DDOC_AUTHORS   = $(B Authors:)$(BR)
		$0$(BR)$(BR)
DDOC_BUGS      = $(RED BUGS:)$(BR)
		$0$(BR)$(BR)
DDOC_COPYRIGHT = $(B Copyright:)$(BR)
		$0$(BR)$(BR)
DDOC_DATE      = $(B Date:)$(BR)
		$0$(BR)$(BR)
DDOC_DEPRECATED = $(RED Deprecated:)$(BR)
		$0$(BR)$(BR)
DDOC_EXAMPLES  = $(B Examples:)$(BR)
		$0$(BR)$(BR)
DDOC_HISTORY   = $(B History:)$(BR)
		$0$(BR)$(BR)
DDOC_LICENSE   = $(B License:)$(BR)
		$0$(BR)$(BR)
DDOC_RETURNS   = $(B Returns:)$(BR)
		$0$(BR)$(BR)
DDOC_SEE_ALSO  = $(B See Also:)$(BR)
		$0$(BR)$(BR)
DDOC_STANDARDS = $(B Standards:)$(BR)
		$0$(BR)$(BR)
DDOC_THROWS    = $(B Throws:)$(BR)
		$0$(BR)$(BR)
DDOC_VERSION   = $(B Version:)$(BR)
		$0$(BR)$(BR)
DDOC_SECTION_H = $(B $0)$(BR)$(BR)
DDOC_SECTION   = $0$(BR)$(BR)
DDOC_MEMBERS   = $(DL $0)
DDOC_MODULE_MEMBERS   = $(DDOC_MEMBERS $0)
DDOC_CLASS_MEMBERS    = $(DDOC_MEMBERS $0)
DDOC_STRUCT_MEMBERS   = $(DDOC_MEMBERS $0)
DDOC_ENUM_MEMBERS     = $(DDOC_MEMBERS $0)
DDOC_TEMPLATE_MEMBERS = $(DDOC_MEMBERS $0)
DDOC_PARAMS    = $(B Params:)$(BR)\n$(TABLE $0)$(BR)
DDOC_PARAM_ROW = $(TR $0)
DDOC_PARAM_ID  = $(TD $0)
DDOC_PARAM_DESC  = $(TD $0)
DDOC_BLANKLINE	= $(BR)$(BR)

DDOC_PSYMBOL	= $(U $0)
DDOC_KEYWORD	= $(B $0)
DDOC_PARAM	= $(I $0)

A Ddoc nem generál HTML kódot. Alap formázó makrók formájára hoz, ami (az előre definiált formájában), HTML-é fejtődik ki. Ha a kimenetre nem mint HTML van szükségünk, akkor ezeket a makrókat újra kell definiálni.

Alap Formázó Makrók (Basic Formatting Macros)

B	az argumentum legyen félkövér
I	az argumentum legyen italic
U	az argumentum legyen aláhúzott
P	az argumentum egy bekezdés
DL	az argumentum egy definíció lista
DT	az argumentum egy definíció a definíció listában
DD	az argumentum egy definíció leírása
TABLE	az argumentum egy táblázat
TR	az argumentum egy sor a táblában
TH	az argumentum egy fejelem bekezdés egy sorban
TD	az argumentum egy adat bekezdés a sorban
OL	az argumentum egy számozott lista
UL	az argumentum egy számozatlan lista
LI	az argumentum egy elem a listában
BIG	az argumentum egy számmal nagyobb szöveg
SMALL	az argumentum egy számmal kisebb szöveg
BR	új sor
LINK	klikkelhető linket generál
LINK2	klikkelhető linket generál, az első argumentum a cím
RED	az argumentum legyen piros
BLUE	az argumentum legyen kék
GREEN	az argumentum legyen zöld
YELLOW	az argumentum legyen sárga
BLACK	az argumentum legyen fekete
WHITE	az argumentum legyen fehér
D_CODE	az argumentum D kód
DDOC	mindenek feletti template a kimenetnek

DDOC speciális azért, mert meghatározza a szabványos szöveget, amibe az egész generált szöveg beillesztődik (reprezentálva a Ddoc által generáld macro BODY-t). Például, abban az esetben, ha style sheet-et akarunk használni, a DDOC újradefiniálás a következő lenne:

DDOC =	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
	<html><head>
	<META http-equiv="content-type" content="text/html; charset=utf-8">
	<title>$(TITLE)</title>
	<link rel="stylesheet" type="text/css" href="style.css">
	</head><body>
	<h1>$(TITLE)</h1>
	$(BODY)
	</body></html>

DDOC_COMMENT-et használjuk arra, hogy a kimeneti fájlba kommenteljünk. A D kód kiemelése a következő makrókkal történik:

D Kód Kiemelő Makrók

D_COMMENT	komment kiemelés
D_STRING	string literálok kiemelés
D_KEYWORD	D kulcsszó kiemelés
D_PSYMBOL	aktuális deklaráció név kiemelés
D_PARAM	aktuális függvény deklaráció paraméterek kiemelése

A kiemelő makrók DDOC_-al kezdődnek. Ezek szabályozzák a prezentáció különálló részeinek formázását.

Ddoc Szekció Formázó Makrók

DDOC_DECL	A deklaráció kiemelése.
DDOC_DECL_DD	A deklaráció leírásának kiemelése.
DDOC_DITTO	Ditto (dettó) deklarációk kiemelése.
DDOC_SECTIONS	Az összes szekció kiemelése.
DDOC_SUMMARY	Az összegző szekció kiemelése.
DDOC_DESCRIPTION	A leíró szekció kiemelése.
DDOC_AUTHORS .. DDOC_VERSION	A megfelelő sztenderd szekció kiemelése.
DDOC_SECTION_H	Egy nem sztenderd szekció nevének kiemelése.
DDOC_SECTION	egy nem sztenderd szekció tartalmának kiemelése.
DDOC_MEMBERS	Alapértelmezett kiemelése minden osztály, struct, stb. tagjainak
DDOC_MODULE_MEMBERS	Egy modul összes tagjának kiemelése.
DDOC_CLASS_MEMBERS	Egy osztály összes tagjának kiemelése.
DDOC_STRUCT_MEMBERS	Egy struct összes tagjának kiemelése.
DDOC_ENUM_MEMBERS	Egy enum típus összes tagjának kiemelése.
DDOC_TEMPLATE_MEMBERS	Egy template összes tagjának kiemelése.
DDOC_PARAMS	Egy függvény paraméter szekció kiemelése.
DDOC_PARAM_ROW	Egy név=érték függvény paraméter kiemelése.
DDOC_PARAM_ID	A paraméter nevének kiemelése.
DDOC_PARAM_DESC	A paraméter nevének kiemelése.
DDOC_PSYMBOL	Annak a deklarációnak a nevének kiemelése, amire egy bizonyos szekció hivatkozik
DDOC_KEYWORD	Kulcsszavak kiemelése.
DDOC_PARAM	Függvény paraméterek kiemelése.
DDOC_BLANKLINE	Beszúr egy üres sort.

Például, a DDOC_SUMMARY a következő képpen definiálható felül:

DDOC_SUMMARY = $(GREEN $0)

És minden összegző szekció zöld lesz.

Makró definíciók az `sc.ini` DDOCFILE-jéből

Egy makró definíciókat tartalmazó szöveg fájl is létrehozható és specifikálható az sc.ini-ben:

DDOCFILE=myproject.ddoc

Makró Definíciók a .ddoc fájlokból a parancssorban

Fájl nevek a DMD parancssorban .ddoc kiterjesztéssel sorban lesznek beolvasva és végrehajtva.

Makró Definíciók a Ddoc által generálva

Makró név	Tartalom
BODY	Beállítja a dokumentum szövegre
TITLE	Beállítja a modul nevét.
DATETIME	Beállítja az aktuális dátumot és időt.
YEAR	Beállítja az aktuális évet.
COPYRIGHT	Beállítja a Copyright: szekció tartalmára, aminek része a modul komment
DOCFILENAME	Beállítja a nevét a generált kimeneti fájlnak

Ddoc használata más Dokumentációkhoz

A Ddoc-ot elsősorban azért hozták létre, hogy beágyazott kommentekből készítsen dokumentációt, de ezen kívül használható még más általános dokumentációk készítésére is, a Ddoc makróinak és a D kód szintakszis kiemelőjének kihasználásával.

Ha a .d forrás fájl a "Ddoc" stringgel kezdődik, akkor általános célú dokumentációként kezelődik, nem mint D kódú forrás fájl. Azonnal a "Ddoc" string után a fájl végéig, illetve bármilyen "Macros:" szekcióig tart a dokumentum. Nem hajtódik végre automatikus kiemelés a szövegben, leszámítva az olyan D kód kiemelését, ami --- közé vannak ágyazva. Csak a makró előfeldolgozás készül el.

Magából a D dokumentációjából is sok oldal generálódott így, pl. ez az oldal is. Az ilyen dokumentumoknak az alján jelölve van, hogy Ddoc-al generálták.

Hivatkozások

A CandyDoc egy nagyon szép példa arra, hogy hogyan lehet testreszabni a Ddoc eredményét makrókkal illetve style sheet-ekkel.

A Digitalmars D programozási nyelv

Beágyazott dokumentációk