A dokumentálás egyik fontos része, egy részletes súgó hozzácsatolása az osztály felületekhez. A KDoc
-al létrehozott HTML class documentation (osztálydokumentáció)
segítí önt és a többi programozót abban, hogy könnyebben használhassák ezeket az osztályokat. A KDevelop teljeskörűen támogatja
a idx
KDoc// használatát a KDE-könyvtár dokumentálásánál, akárcsak az ön által már dokumentált alkalmazás-szerkezeteket.
A meglevő kódok megismeréséhez, jó elolvasni a beépített online dokumentációt. A következőkben leírást olvashat arról, hogy hogyan
juthat hozzá az API dokumentációjához, hogy hol segíti önt a KDevelop, és hogy milyen speciális függelékeket biztosít még a KDoc
ezeken kívül.
Miután létrehozott egy projektet, válassza a "Make API-Doc" -ot a "Projekt" menüből, hogy elkészítse a API dokumentációt. Így elkészül a fejléc állomány, és a HTML formátumú kimenet. Ezután bármikor hozzáférhet a dokumentációhoz, ha kiválasztja a súgó menüből az "API-Documentation" -t, vagy az odavágó könyv-szimbólumot a dokumentációs fában, a "Jelenlegi projekt" útvonalon.
A KDE-hez és az Qt online-idx/class documentation/ -hoz már megvannak a dokumentáció kereszthivatkozásai, így könnyen követheti az inheritance-t az inheritance áttekintővel. Ez nagymértékben segítheti ismerkedését a KDE-vel és a Qt dokumentációval.
A KDevelop minden eszközt biztosít a kód automatikus hozzáadásához, és a közvetlen dokumentálást is támogatja. Amikor az Osztálygenerátort a "Projekt"->"Új osztály" kiválasztásával használja, adjon meg részletes leírást a dokumentációs mezőben. Így a dokumentáció bekerül az osztály fejlécébe.
Mikor osztálytag-funkciót, vagy attributumot csatol a classtools (osztálykellék) segítségével, akkor csatolja a tag dokumentációját az odavágó dokumentációs mezőbe.
Azt is gondolhatja persze, hogy a dokumentálás nem különösebben fontos része a fejlesztési folyamatnak. Gondoljon azonban arra, hogy ahogyan a projekt mérete nő és egyre több ember kapcsolódik be a fejlesztésbe, akkor a class documentation (osztály-dokumentáció) a legjobb módja annak, hogy időt spóroljunk. Ha a fejlesztőnek az eljárás nevéből kell kitalálnia annak funkcióját, akkor a nevek félreértelmezése miatt könnyen előfordulhat, hogy az eljárás teljesen mást csinál, mint amire a neve esetleg utal és amit fejlesztő vár. Ezért fordítson kellő gondot a dokumentálásra és frissítse azt olyan gyakran, ahogyan az lehetséges.
Mindamellett, a dokumentáció nem tartozik a projekthez, és nincs nemzetköziesítési támogatottsága sem. Ezért minden API dokumentációt angolul kell megadni, hogy a nemzetközi fejlesztői csoportok dolgozhassanak ezekkel a forrásokkal.
Amennyiben kézzel szeretné a dokumentációt hozzáadni a fejlécállományhoz, akkor adja a dokumentációt above az eljáráshoz, vagy az osztályhoz C-comment stílusban, azzal a különbséggel, hogy az első sornak itt perjellel és kettő csillaggal kell kezdődnie.
Példa:
/** engedélyezi a menüket/eszköztár ikonokat
*/
void enableCommand(int id_);
NOTE: Ennek a fejezetnek a dokumentációja az KDoc leírásából származik, amit Sirtaj S. Kang taj@.kde.org), az KDoc szerzője írt az KDoc -hoz; Copyright (c) 1997
A dokumentáció a következők elegye:
<pre> .....kód töredékek.... </pre>
@tagname [tag parameters]
Érvényes függelékek mindenféle forráskódhoz:
@short [a szöveg egy mondata]
Az osztály rövid leírása
@author [a szöveg egy mondata]
Az osztály szerzője
@version [a szöveg egy mondata]
Osztályverzó (Én általában azt a RCS/CVS "Id" függelékben állítom be)
@see [hivatkozás(ok) osztályokra, eljárásokra]
Hivatkozás más, kapcsolódó dokumentációkra
@see
lsd. mint fent
@return [egy mondat]
Egymondatos leírás a return értékről
@param [param név azonosító] [param leírás]
Irja le a paramétert. A param leírás sokféle sor között lehet,
de mindig üres sorra végződik a megjegyzés végénél, vagy egy
másik param elejénél. Ezért a paraméterek jó ha a dokumentum
végén szerepelnek.
@see
mint fent
@ref
A "@ref" metafüggelék, mint a javadoc formatum alapja, ugyanabban a formátumban van, mint a @see, azzal a különbséggel, hogy bárhol előfordulhat a dokumentációban.
(az összes többi függeléknek a saját sorában kell lennie).