Következő Előző Tartalom

10. Osztály dokumentáció a KDoc segítségével

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 idxKDoc// 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.

10.1 Hogyan használjuk a KDevelop dokumentációs képességeit

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.

10.2 Osztály- és Tagdokumentáció hozzáadása (member)

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_);

10.3 Különleges függelékek:

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:

Érvényes függelékek mindenféle forráskódhoz:


Következő Előző Tartalom