Aki még nem foglalkozott a dokumentáció készítés ezen lehetőségével, annak is biztos feltűnt már, hogy a Visual Studio.NET által generált forráskódok függvényei előtt olyan megjegyzések kapnak helyet, melyek három per jellel (///) kezdődnek. Ezek olyan speciális megjegyzések, melyek xml formátumú szöveget, egyéb információkat tartalmaznak. Ezen bejegyzésekből a Visual Studio.NET képes elkészíteni a forráskódok dokumentációját. Mivel ilyen megjegyzéseket mi is létrehozhatunk saját osztályainkhoz, függvényeinkhez, így a teljes alkalmazásunk forráskódjának dokumentációját legeneráltathatjuk majd a programunk fordításakor. Ha változik egy függvényünk funkciója, akkor nincs más dolgunk, mint az előtte lévő megjegyzésünk szövegét módosítani, majd a projekt újra fordításakor máris elkészül az új dokumentáció.
Ahhoz, hogy ez a dokumentáció, vagyis ez az XML állomány a programunk fordításakor létrejöjjön, szükséges egy apró beállítást elvégeznünk a projekt konfigurációjában. Ehhez válasszuk az aktuális projektet a Solution Exporer-ben, majd a Project - Properties menüponttal nyissuk meg ezt az ablakot. Ebben a Configuration Properties - Build elemnél megjelenő XML Documentation File tulajdonsághoz kell megadnunk egy tetszőleges nevű XML állományt. Az itt megadott állományba kerül majd a dokumentáció a program lefordításakor.
Nézzük most miképpen is kell egy-egy ilyen speciális megjegyzést elkészítenünk. Nagyon sok lehetőségünk van ilyen esetben, de most nézzük kezdetnek a legegyszerűbb példát: létrehozunk az alkalmazásban egy függvényt és ehhez készítünk egy megjegyzést, melyben csak azt írjuk le, hogy ez a függvényünk mire szolgál. Ebben az esetben a <function></function> címkék közé kell tennünk a függvényünk leírását. Ebből tudja majd a dokumentációkészítő, hogy itt egy függvény leírását adjuk meg.
/// <function>
/// Func1 függvény leírása
/// </function>
private void Func1()
{
}
Ha most lefordítjuk a projektet, akkor létrejön a megadott Doc.xml állomány. Nézzük mit is tartalmaz ez:
<?xml version="1.0"?>
<doc>
<assembly>
<name>Document</name>
</assembly>
<members>
...
<member name="M:Document.Form1.Func1">
<function>
Func1 függvény leírása
</function>
</member>
</members>
</doc>
Látható, hogy sok más egyéb mellett a mi megjegyzésünk is bekerül a dokumentációba.
A dokumentációkészítéshez azonban nem csak a <function> címke használható, hanem még nagyon sok más lehetőségünk is van. Tekintsük át ezeket vázlatosan:
| Bejegyzés |
Leírás |
| c |
Egysoros szöveg megjelölése kódként. |
| code |
Többsoros szöveg megjelölés kódként. |
| example |
A függvényünk felhasználásához mellékelhetünk forráskód példát. |
| exception |
Saját Exception osztályunk leírására szolgál. A cref attribútumban adhatjuk meg, hogy Exception osztályunk miből származik. Pl.: cref="System.Exception". |
| include |
Másik XML dokumentációra, illetve annak egy részére hivatkozhatunk az XML nyelv XPath szintaktikája szerint. A file attribútumban az XML állományt kell megadnunk, míg a path-ban az XML-ben lévő leírás helyét. |
| list |
Készíthetünk felsorolást, mely lehet akár számozott is, valamint táblázatot is. |
| para |
Új bekezdést jelölhetünk vele. |
| param |
Függvényünk paramétereinek leírását adhatjuk meg. A name attribútumba kerül. |
| paramref |
Egy szöveg leírásában ha hivatkozni szeretnénk egy paraméterre név szerint, akkor ezt a paramref segítségével tehetjük meg. A name attribútumba adhatjuk meg a paraméter nevét. |
| permission |
Az adott osztály, függvény eléréséhez szükséges jogokat írja le. A cref attribútumba adható meg a hozzáférést szabályzó osztály. Pl.: cref="System.Security.PermissionSet". |
| remarks |
Megjegyzés írható. |
| returns |
Függvényünk visszatérési értékének leírása. |
| see |
Hivatkozás a dokumentáció egy másik részére. A cref attribútumba adható meg a hivatkozás célja. |
| seealso |
„Lásd még” szekció létrehozása. A cref attribútumba adható meg a hivatkozás célja. |
| summary |
Az adott objektum összefoglaló leírása. |
| value |
Property értékének leírása. |