Javadoc. Dokumentációs megjegyzés (2) Dokumentációs megjegyzés (1) Dokumentációs megjegyzés felépítése



Hasonló dokumentumok
Javadoc. Jeszenszky Péter Debreceni Egyetem, Informatikai Kar Utolsó módosítás: április 13.

Java II. I A Java programozási nyelv alapelemei

OBJEKTUM ORIENTÁLT PROGRAMOZÁS JAVA NYELVEN. vizsgatételek

és az instanceof operátor

Java VIII. Az interfacei. és az instanceof operátor. Az interfészről általában. Interfészek JAVA-ban. Krizsán Zoltán

Programozási nyelvek JAVA EA+GY 1. gyakolat

Az osztályok csomagokba vannak rendezve, minden csomag tetszőleges. Könyvtárhierarhiát fed: Pl.: java/util/scanner.java

SZOFTVERES SZEMLÉLTETÉS A MESTERSÉGES INTELLIGENCIA OKTATÁSÁBAN _ Jeszenszky Péter Debreceni Egyetem, Informatikai Kar jeszenszky.peter@inf.unideb.

Java II. I A Java programozási nyelv alapelemei

Szoftvertechnolo gia gyakorlat

Osztályok. 4. gyakorlat

Java programozási nyelv 4. rész Osztályok II.

Saját Subversion tároló üzemeltetése i. Saját Subversion tároló üzemeltetése

Java VI. Egy kis kitérő: az UML. Osztály diagram. Általános Informatikai Tanszék Utolsó módosítás:

Regionális forduló november 19.

Programozási nyelv Java

A függvény kód szekvenciáját kapcsos zárójelek közt definiáljuk, a { } -ek közti részt a Bash héj kód blokknak (code block) nevezi.

JUnit. JUnit használata. IDE támogatás. Parancssori használat. Teszt készítése. Teszt készítése

Programozás I. 1. gyakorlat. Szegedi Tudományegyetem Természettudományi és Informatikai Kar

Bevezető. Servlet alapgondolatok

Regionális forduló november 19.

Forráskód formázási szabályok

Java programozási nyelv 6. rész Java a gyakorlatban

Abstract osztályok és interface-ek. 7-dik gyakorlat

Objektum orientáltság alapjai A Java nyelv Fordítás - futtatás

Az R használata (tárgyalt R verzió: ) Jeszenszky Péter Debrecen Egyetem, Informatikai Kar jeszenszky.peter@inf.unideb.hu

Mi a különbség az extends és az implements között. Mikor melyiket kell használni? Comperable-t megvalósító oasztályokban össze lehet hasonlitani

Gyakorlati vizsgatevékenység A

Java I. A Java programozási nyelv

XCZ állományok ellenőrzése, átadása elektronikus beküldésre és közvetlen beküldése parancssori funkcióval az ÁNYK programban

Pénzügyi algoritmusok

OOP: Java 8.Gy: Abstract osztályok, interfészek

Java programozási nyelv 5. rész Osztályok III.

JAVA PROGRAMOZÁS 2.ELŐADÁS

OOP és UML Áttekintés

Java V. Osztályszint. lyszintű ű tagok. Példányváltozó. Osztályváltozó. Általános Informatikai Tanszék Utolsó módosítás:

Web-technológia PHP-vel

Java IX. telkezelés a Java-ban

Programozási technológia I.

Karakterkészlet. A kis- és nagybetűk nem különböznek, a sztringliterálok belsejét leszámítva!

Stateless Session Bean

Címkék és ágak kezelése i. Címkék és ágak kezelése

Java IX. telkezelés a Java-ban

Mechatronika és mikroszámítógépek 2017/2018 I. félév. Bevezetés a C nyelvbe

Viczián István IP Systems JUM XIX szeptember 18.

Ficsor Lajos Általános Informatikai Tanszék Miskolci Egyetem

A legfontosabb DOS parancsok

Programozási nyelvek II. JAVA EA+GY 1. gyakolat

C programozási nyelv

Útmutató az OKM 2007 FIT-jelentés telepítéséhez

Osztályok. construct () destruct() $b=new Book(); $b=null; unset ($b); book.php: <?php class Book { private $isbn; public $title;

Segédanyag: Java alkalmazások gyakorlat

Objektum Orientált Programozás. 11. Kivételkezelés 44/1B IT MAN

A TERC VIP költségvetés-készítő program telepítése, Interneten keresztül, manuálisan

strings.xml res/values/strings.xml fájlban hozzuk létre a hiányzó string adatforrásainkat A jelenlegi helyett ez álljon: <resources> <string

Helyes-e az alábbi kódrészlet? int i = 1; i = i * 3 + 1; int j; j = i + 1; Nem. Igen. Hányféleképpen lehet Javaban megjegyzést írni?

Java és web programozás

Egészítsük ki a Drupal-t. Drupal modul fejlesztés

Java VI. Miskolci Egyetem Általános Informatikai Tanszék. Utolsó módosítás: Ficsor Lajos. Java VI.: Öröklődés JAVA6 / 1

A Java EE 5 plattform

BASH SCRIPT SHELL JEGYZETEK

RapidMiner telepítés i. RapidMiner telepítés

TERC V.I.P. hardverkulcs regisztráció

Széchenyi István Egyetem. Programozás III. Varjasi Norbert

Szervlet-JSP együttműködés

1. Mi a fejállományok szerepe C és C++ nyelvben és hogyan használjuk őket? 2. Milyen alapvető változókat használhatunk a C és C++ nyelvben?

Szoftvergyártás: gyártásvezérlés kód-figyeléssel

Java és web programozás

Objektumorientált programozás C# nyelven

Aspektus-orientált nyelvek XML reprezentációja. Kincses Róbert Debreceni Egyetem, Informatikai Intézet

Adatbázis Rendszerek II. 5. PLSQL Csomagok 16/1B IT MAN

ÁNYK53. Az Általános nyomtatványkitöltő (ÁNYK), a személyi jövedelemadó (SZJA) bevallás és kitöltési útmutató együttes telepítése

Könyvtári címkéző munkahely

Programozási nyelvek Java

Gyakorlati vizsgatevékenység B

Collections. Összetett adatstruktúrák

Algoritmizálás és adatmodellezés tanítása beadandó feladat: Algtan1 tanári beadandó /99 1

C# nyelv alapjai. Krizsán Zoltán 1. Objektumorientált programozás C# alapokon tananyag. Általános Informatikai Tanszék Miskolci Egyetem

Programozási alapismeretek beadandó feladat: ProgAlap beadandó feladatok téma 99. feladat 1

List<String> l1 = new ArrayList<String>(); List<Object> l2 = l1; // error

Occam 1. Készítette: Szabó Éva

Kivételek kezelése (exception handling) Hibakezelés old style. Kivételkezelés

AWK programozás, minták, vezérlési szerkezetek

Java-s Nyomtatványkitöltő Program Súgó

E-Freight beállítási segédlet

BŐVÍTMÉNYEK TELEPÍTÉSE ÉS SZERKESZTÉSE WORDPRESS-BEN

Programozási nyelvek Java

1 Rendszerkövetelmények

EuroOffice Professzionális Vonalkód és QR kód generátor

C# Nyelvi Elemei. Tóth Zsolt. Miskolci Egyetem. Tóth Zsolt (Miskolci Egyetem) C# Nyelvi Elemei / 18

Adóhátralék kezelés egyszerűen. Telepítési útmutató. A program futtatásához Windows XP, Windows 7, 8 operációs rendszer szükséges.

AWK programozás Bevezetés

Szoftver alapfogalmak

Objektumok inicializálása

Bisonc++ tutorial. Dévai Gergely. A szabály bal- és jobboldalát : választja el egymástól. A szabályalternatívák sorozatát ; zárja le.

Multimédia 2017/2018 II.

A szerzõrõl... xiii Bevezetés... xv

HTML é s wéblapféjlészté s

Átírás:

Javadoc Dokumentációs megjegyzés (2) Jeszenszky Péter Debreceni Egyetem, Informatikai Kar jeszenszky.peter@inf.unideb.hu Verzió: 2015.0 Utolsó módosítás: 2015. április 21. Tartalmazhatja a forráskódban egyetlen sor, mint például: Egysoros dokumentációs megjegyzés. Megadható több sorban, mint például: Ez pedig egy több sorból * álló dokumentációs * megjegyzés. A feldolgozás során a határolók között a sorok elejéről elhagyásra kerülnek a whitespace és * karakterek Ha egy sor elején nincs * karakter, akkor nem kerülnek elhagyásra a whitespace karakterek a sor elejéről Ez hasznos például programkód pre elemben történő megadása esetén 3 Dokumentációs megjegyzés (1) Dokumentációs megjegyzés felépítése A forráskódban és határolók között elhelyezett megjegyzés Nem hivatalosan Javadoc megjegyzésnek is nevezik Osztály, interfész, metódus, konstruktor vagy adattag deklarációja előtt helyezhető el Egyéb helyeken figyelmen kívül lesznek hagyva A megjegyzés szövegét HTML-ben kell megadni Használható a HTML bármelyik verziója A szövegben ügyelni kell a < és & karakterek használatára (megadásuk < és & módon történhet) 2 Az alábbi két részből áll: Fő leírás (main description): a határoló után kezdődik és a címke szakasz elejéig tart, annak hiányában a határolóig Címke szakasz (tag section): az első olyan @ karakterrel kezdődik, amely a sor elején jelenik meg, ha elhagyjuk annak elejéről a vezető * karaktereket, a whitespace karaktereket és a határolót Ha a fő leírásban sor elején kell olyan @ karaktert megadni, amely nem a címke szakasz elejét jelzi, használjuk az @ karakterhivatkozást Megadható fő leírást nem tartalmazó, csak címke szakaszból álló dokumentációs megjegyzés 4

Fő leírás (1) Több adattag dokumentálása Az első mondat a dokumentált entitás (például osztály, metódus) tömör összefoglalását kell, hogy tartalmazza Angol nyelv esetén az első mondat végét az a pont karakter jelzi, melyet szóköz, tabulátor vagy újsor karakter követ Ha egy ilyen pont karakter nem az első mondat végét jelezi, akkor az egyedhivatkozással adjuk meg a szóközt, vagy helyezzünk el egy megjegyzést <!-- és --> határolók között közvetlenül a pont karakter után Az angoltól eltérő nyelveknél a fenti megoldás nem működik, ilyenkor a problémás írásjelet karakterhivatkozással (.) adjuk meg helyette 5 Kerülendő az alábbi: * Az intervallum eleje és vége. public int start, end; A dokumentációs megjegyzés ilyenkor le lesz másolva mindkét adattaghoz 7 Fő leírás (2) Címkék (1) A felhasználó nyelvi beállításai határozzák meg a dokumentációs megjegyzések nyelvét Linux környezetben lásd a LANG környezeti változó értékét Az operációs rendszer szintű nyelvi beállítások felülbírálása: A Javadoc program parancssorból történő futtatásakor adjuk meg a -locale opciót, mint például -locale en_us A Maven Javadoc Plugin esetén használjuk a locale paramétert vagy az azonos nevű tulajdonságot 6 A dokumentációs megjegyzésekben használható speciális kulcsszavak, melyekben a kis és nagybetűk különbözőek! Kétfajta címke használható: blokk címke és szövegközi címke Szövegközi címkék esetén megszorítások lehetnek arra, hogy a címke hol megengedett a megjegyzésben Blokk címkék esetén megszorítások lehetnek az előfordulások számára 8

Címkék (2) Csomagokhoz tartozó megjegyzés állományok Blokk címke (block tag): @címke formában adhatók meg a sor elején, opcionálisan megengedettek előttük whitespace és * karakterek @author, @param A címkéhez a kulcsszót követő szöveg tartozhat, melyet akár több sor is tartalmazhat A szöveg a következő blokk címkéig vagy a dokumentációs megjegyzés végét jelző határolóig tart Szövegközi címke (inline tag): {@címke} formában adhatók meg a megjegyzésben bárhol, ahol szöveg megengedett Csomagok dokumentálásához az ajánlott megoldás: Helyezzünk el a csomagban egy packageinfo.java nevű állományt, melynek tartalmát az alábbi példa szemlélteti: * Segédosztályokat tartalmazó csomag. package my.util; A dokumentációs megjegyzésben csak bizonyos blokk és szövegközi címkék megengedettek {@code}, {@link} 9 11 Példa Áttekintő megjegyzés állományok (1) A JDK6 java.util.linkedlist osztályának forrásából: * Pops an element from the stack represented by this list. * In other words, removes and returns the first element of * this list. * * <p>this method is equivalent to {@link #removefirst()}. * * @return the element at the front of this list (which is * the top of the stack represented by this list) * @throws NoSuchElementException if this list is empty * @since 1.6 public E pop() { return removefirst(); } Megadható a teljes alkalmazásra vagy több csomagra vonatkozó dokumentáció, melyet külön állomány tartalmaz Ennek neve tetszőleges lehet, de tipikusan overview.html használt a gyakorlatban Tipikusan a csomagokat tartalmazó könyvtárszerkezet tetején helyezik el Az állomány elérési útvonalát a Javadoc eszköznek a -overview opcióval kell megadni, Apache Maven használata esetén pedig a -Doverview= opcióval a megfelelő bővítménynek (Maven Javadoc Plugin) 10 12

Áttekintő megjegyzés állományok (2) Rendelkezésre álló címkék Az állományt HTML-ben kell megírni Szövegközi címkék: Blokk címkék: Kötelező a body elem megadása, melynek tartalma kerül másolásra a dokumentáció generálásakor Példa az állomány tartalmára: <html> <body> <p>nyílt forrású osztálykönyvtár racionális számok kezeléséhez. A fő funkcionalitást a {@link my.math.fraction} csomag tartalmazza.</p> </body> </html> Bizonyos blokk és szövegközi címkék is használhatók 13 {@code} {@docroot} {@inheritdoc} {@link} {@linkplain} {@literal} {@value} @author @deprecated @exception @param @return @see @serial @serialdata @serialfield @since @throws @version 15 Megjegyzések automatikus másolása Szövegközi címkék használata Metódusok dokumentációs megjegyzései örökölhetők a szülőosztálytól és az implementált interfészektől Ez nem vonatkozik a konstruktorokra! Ha egy dokumentációs megjegyzésben hiányzik a fő leírás, a @return, @param vagy @throws címkék valamelyike, akkor ezek automatikus másolása @throws címke másolása csak akkor, ha a kivétel dobását deklarálja a metódus! A dokumentáció másolása explicit módon kérhető az {@inheritdoc} szövegközi címkével A fő leírásban, @return, @param és @throws címkékhez tartozó szövegben használható Címke Áttekintő megjegyzés állomány Csomag megjegyzés állomány Osztály/ interfész Adattag Konstruktor Metódus {@code} {@docroot} {@inheritdoc} {@link} {@linkplain} {@literal} {@value} 14 16

Blokk címkék használata Szövegközi címkék (2) Címke Áttekintő megjegyzés állomány Csomag megjegyzés állomány Osztály/ interfész Adattag Konstruktor Metódus {@inheritdoc} @author @deprecated Dokumentáció másolása a legközelebbi ősosztályból vagy implementált interfészből @exception @param @return Csak metódushoz tartozó dokumentációs megjegyzésben használható az alábbi helyeken: Fő leírásban (csak a fő leírást másolását eredményezi) @see @serial A @return, @param és @throws blokk címkékhez tartozó szövegben (csak a megfelelő címkéhez tartozó szöveg másolását eredményezi) @serialdata @serialfield @since @throws @version 17 * {@inheritdoc} * * <p>this implementation always throws an * {@code UnsupportedOperationException}. 19 Szövegközi címkék (1) Szövegközi címkék (3) {@code szöveg} {@link csomag.osztály#tag címke} A szöveg megjelenítése fix szélességű betűtípussal (programkódként) A szövegben szabadon használható a < és & karakter, { karakter az } karakterhivatkozással adható meg {@code true}, {@code e1.hashcode() == e2.hashcode()} {@docroot} A generált állományokat tartalmazó könyvtárstruktúra gyökerének relatív elérési útvonalát szolgáltatja Hiperhivatkozás az adott csomag, osztály, interfész, metódus, konstruktor vagy adattag dokumentációjára (megjelenítése fix szélességű betűtípussal) {@link my.math} {@link my.math.fraction} {@link my.math.fraction#zero} {@link my.math.fraction#fraction(int,int)} {@link my.math.fraction#add(int)} {@linkplain csomag.osztály#tag címke} <a href="{@docroot}/../copyright.html">copyright</a> 18 Ugyanaz, mint a {@link}, csak normál betűtípussal történik a megjelenítés 20

Szövegközi címkék (4) Blokk címkék (1) {@literal szöveg} @author szöveg Ugyanaz, mint a {@code}, csak a szöveg megjelenítése normál betűtípussal történik {@value csomag.osztály#adattag} Szerzők nevének megadására szolgáló címke, melyből egy dokumentációs megjegyzésben több is előfordulhat @author Péter Jeszenszky @deprecated szöveg Az adott konstans adattag értékét szolgáltatja, csak final módosító esetén használható Azt jelzi, hogy a dokumentált entitás elavult, használata kerülendő A szöveg első mondatában jelezni, hogy mióta, és a helyettesítőt is * The value of this constant is {@value}. public static final int DEFAULT_VALUE = 7; 21 Használata esetén a dokumentált entitáshoz adjuk meg a @Deprecated annotációt is! Egy dokumentációs megjegyzésben egyszer fordulhat elő @deprecated As of version 1.1, replaced by {@link #newmethod(int)}. 23 Általános irányelvek a blokk címkék használatára Blokk címkék (2) A többször is előforduló blokk címkéket egy csoportban ajánlott megadni @exception kivételosztály leírás Ugyanaz, mint a @throws Az alábbi sorrendben ajánlott a megadás: @param paraméternév leírás @author, @version, @param, @return, @exception/@throws, @see, @serial/@serialfield/@serialdata, @deprecated Az adott nevű paraméter leírást szolgáltatja Típusparaméter esetén a nevet < és > határoló karakterek között kell megadni Egy dokumentációs megjegyzésben egy adott nevű paraméterhez csak egyszer fordulhat elő A @param címkéket az paraméterek sorrendjének megfelelően ajánlott megadni 22 @param e the element to add 24

Blokk címkék (3) Blokk címkék (5) @return leírás @since szöveg Metódus visszatérési értékét szolgáltatja Egy dokumentációs megjegyzésben csak egyszer fordulhat elő A szoftver azon verziójának megadására szolgál, amelyben megjelent a dokumentált entitás @since 1.2 @throws kivételosztály leírás Metódus vagy konstruktor által dobott kivétel dokumentálására szolgál Több @throws címke esetén ajánlott a kivételosztályok neve alapján ábécé sorrendbe rendezni ezeket 25 @throws IOException if an I/O error occurs 27 Blokk címkék (4) Blokk címkék (6) @see hivatkozás @version szöveg Hivatkozás elhelyezésére szolgál, többféle módon használható, egy dokumentációs megjegyzésben akár többször is előfordulhat: @see "szöveg" módon, mint például: @see "The Java Programming Language" @see <a href="uri-hivatkozás">címke</a> módon, mint például: @see <a href="http://jcp.org/en/jsr/detail?id=173">jsr 173: Streaming API for XML</a> A szoftver verziójának a jelzésére szolgál, amelynek része a dokumentált entitás Egy dokumentációs megjegyzésben akár többször is előfordulhat @version 1.73, 05/10/06 @see csomag.osztály#tag címke módon, a {@link} címkéhez hasonlóan, mint például: @see java.lang.system#currenttimemillis() 26 28

API dokumentáció generálása (1): Javadoc eszköz API dokumentáció generálása (3): Eclipse IDE Az alábbi példa szemlélteti a program használatát: javadoc -d build/apidocs \ célkönyvtár -encoding UTF-8 \ a források karakterkódolása -charset UTF-8 \ HTML karakterkódolás -sourcepath src/main/java \ a forrásokat tartalmazó könyvtár my.gui my.util csomagok, amelyekből dokumentációt kell generálni Válasszuk az alábbi menüpontot: Project Generate Javadoc 29 31 API dokumentáció generálása (2): Apache Maven További információk Használjuk a Maven Javadoc Plugin javadoc célját, ehhez az mvn javadoc:javadoc parancsot kell végrehajtani Javadoc Technology http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/ A reporting elemben hivatozzunk a bővítményre, az API dokumentáció a webhely része lesz <reporting> <plugins>... <plugin> <groupid>org.apache.maven.plugins</groupid> <artifactid>maven-javadoc-plugin</artifactid> <version>2.10.3</version> </plugin>... </plugins> </reporting> How to Write Doc Comments for the Javadoc Tool http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html Requirements for Writing Java API Specifications http://www.oracle.com/technetwork/java/javase/documentation/index-142372.html Maven Javadoc Plugin http://maven.apache.org/plugins/maven-javadoc-plugin 30 32