A TTCN-3 programozási nyelv

Forráskód dokumentáció

Az egyre nagyobb méretű TTCN3 programok írásánál felmerült az igény a forráskód dokumentáció egységes kezelésére. Ennek előnye többek között az automatikus feldolgozhatóság. Például

Hasonló eszközök rendelkezésre állnak más nyelvekhez. Például Java-hoz a Javadoc dokumentációs jelölés. C/C++-ra főleg a Natural Docs dokumentáció generáló (és ezzel együtt a dokumentációs forma is) terjedt el. Mára a TTCN-3 szabványba is bekerült egy rész, ami a forráskód dokumentáció szintaxisát és szemantikáját definiálja. Ez a leírás egy összefoglalót ad a szabvány ide vonatkozó részéről.

Forráskód dokumentációval a következő nyelvi elemek láthatók el:

Struktúra

Egy dokumentációs elem a következőkből épül fel

Elhatároló jelek

Ezek alapján különíthető el a forráskódtól. Jele több soros komment esetén "/**" és "*/", egy soros esetén "//*".

Törzs

A határoló jelek közötti terület. Tartalma a dokumentációs szöveg, illetve tartalmazhat formázási információkat, valamint tag-eket.

Formázási jelek

A dokumentáció használhat formázási jeleket a HTML oldalakhoz hasonlóan. A HTML formázási tag-eknek egy részhalmaza használható. A jelek használatával kapcsolatos információkat a HTML szabvány tartalmazza, itt csak felsorolás szintjén említjük meg őket:

A fenti elemek kezelése a szabvány minimális követelése. Egyes eszközök a fentieken kívül egyéb tag-eket is támogathatnak.

Tag-ek

A tag-ek célja a dokumentációs blokk szemantikus tagolása, valamint a dokumentáció egyes részeinek a forráskódhoz való rendelése. A szabvány meghatározza, hogy mely nyelvi elemekhez mely tag-ek rendelhetők. A legegyszerűbb példa: paramétert jelölő tag csak olyan nyelvi elem dokumentációjában szerepelhet, ami rendelkezik formális paraméterrel. A tag-ek nagy része ismerős lehet más nyelvekből, egyesek viszon a tesztel

@author

Az adott elem létrehozójának neve. Lehet személy, vagy szervezet. Ha többen vannak, vesszővel elválasztva. Használat:

/** @author Teszt Elek */ module Module1{}
@config

Ez a tag csak testcase esetén alkalmazható. A tesztkonfiguráció leírására/hivatkozására szolgál.

Használat:
/** @config Az xy dokumentum 12. fejezetében található. */ testcase tc_1() runs on MyMTC{}
@desc

Általános tag. Az adott elem leírására szolgál. pl használat, funkcionalitás

Használat:
/** @desc Ezen a porton érjük el a szervert. */ modulepar integer TCPPortNum := 5555;
@member

Az adott tipusdefinició egyes mezőinek leírására használható. Használat:

//* @member szamlalo Ez a mezo a szamlalot reprezentalja //* @member nevezo Ez a mezo a nevezot reprezentalja type record Racionalis{ integer szamlalo, integer nevezo }
@param

Formális paramétert irhatunk le vele.

Használat:
/** @param strToLog A string amit ki szeretnenk logolni. */ function f_1(in charstring strToLog) runs on MyMTC{ log(strToLog); }
@purpose

Ez a tag csak testcase esetén alkalmazható. A teszt céljának leírására szolgál.

Használat:
/** @purpose Ellenorzi, hogy a server megszakitja-e a kapcsolatot a specifikacióban meghatarozott ido elteltevel. */ testcase tc_testTimeOut() runs on MyMTC{}
@remark

Extra információ az adott testcase-zel/ függvénnyel kapcsolatban.

Használat:
/** @remark Hivas elott fel kell epiteni a kapcsolatot */ testcase tc_testTimeOut() runs on MyMTC{}
@return

A függvény visszatérési értékét írhatjuk le vele.

Használat:
/** @return A két szám összege. */ function f_add(in integer a, in integer b) runs on MyMTC return integer{ return a + b; }
@see

Egy másik globálisan látható definíció hivatkozható ezzel a tag-gel.

Használat:
//* @remark Hivas elott fel kell epiteni a kapcsolatot //* @see MyModule.f_connect testcase tc_testTimeOut() runs on MyMTC{}
@since

Jelölhetjük, hogy az adott elem a modul melyik verziójától elérhető.

Használat:
//* @since 1.1 testcase tc_testTimeOut() runs on MyMTC{}
@status

Leirhatjuk vele, hogy az adott elem a fejlesztés melyik fázisában van jelenleg. Értékei a szabvány által nem meghatározottak.

Használat:
//* @status draft testcase tc_testTimeOut() runs on MyMTC{}
@url

Külső erőforrás URL cimét adhatjuk meg a tag után.

Használat:
//* @url https://www.ietf.org/rfc/rfc793.txt testcase tc_testTimeOut() runs on MyMTC{}
@verdict

Leírja, hogy melyik verdict milyen esetekben állítódik be az adott testcase/függvény futtatása alatt.

Használat:
//* @verdict pass The connection is dropped after x milisecs of inactive time //* @verdict fail The connection is still alive after x milisecs testcase tc_testTimeOut() runs on MyMTC{}
@priority

Az adott teszteset prioritása

Használat:

//* @priority high testcase tc_testTimeOut() runs on MyMTC{}
@requirement

Az adott requirement, amit a teszt eset hivatott tesztelni.

Használat:
//* @requirement RS1234/7594 testcase tc_testTimeOut() runs on MyMTC{}
@reference

Referencia külső hivatkozásra.

Használat:
//* @reference ETSI TS 100 974 v7315.0 (2004-03) type record MyPDU { }
Tag-ek vs nyelvi elemek

A lenti táblázat összefoglalja, hogy mely nyelvi elemhez mely tagek használhatók a dokumentációs blokkokban.

Simple Data Types Structured Data Types Component Types Port Types Modulepars Constants Templates Signatures Functions Altsteps Test Cases Modules Groups Control Parts
@author X X X X X X X X X X X X X X
@config X
@desc X X X X X X X X X X X X X X
@exception X
@member X X X X X X
@param X X X X X
@priority X
@purpose X X
@remark X X X X X X X X X X X X X X
@reference X X X X X X X X X X X X X X
@requirement X X X X
@return X X
@see X X X X X X X X X X X X X X
@since X X X X X X X X X X X X X X
@status X X X X X X X X X X X X X X
@url X X X X X X X X X X X X X X
@verdict X X X X
@version X X X X X X X X X X X X X X