A KDevelop Programozói Kézikönyv: Osztály dokumentáció a KDoc segítségével

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 `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.

## 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:

- Normál szöveg. A bekezdéseket legalább egy üres sorral kell elválasztani egymástól.
- az ív szövege

      <pre>
      .....kód töredékek....
      </pre>

- Az ív különböző függelékei:

  > `

  >     @tagname [tag parameters]

  > `

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

- Osztályok

  > `

  >       @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

  > `

- Eljárások

  > `

  >       @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.

  > `

- Constants, Enums, Properties

  > `

  >       @see
  >         mint fent

  > `

- ALSO `@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).

Következő Előző Tartalom