Dokumentimi i API - Naser Kastratinaserkastrati.weebly.com/uploads/3/8/8/3/38831473/docs-06.pdf ·...

HyrjeDokumentimi i kodit burimor

Përfundim

Dokumentimi i API

Faton Berisha

Fakulteti i Shkencave KompjuterikeUniversiteti i Prizrenit

Dokumentimi i API 1


Përfundim

Përmbajtja

1 Hyrje

2 Dokumentimi i kodit burimor

Dokumentimi i API 2


Përfundim

Hyrje

Krijimi i referencavePërdorimi i veglës JavaDoc për krijimin e API të një kodi nëJava si dokumentacion referencimi

Dokumentimi i API 3


Përfundim

Programimi ndaj-dhe-pushto

Rikujtoni parimet bazë të paradigmës OOPNdajeni programim në pjesë të menagjueshme që mund tëimplementohen, testohen të izoluara.

Struktura e komponentaveDefinoni interfejsat për pjesët për të komunikuar me njëratjetrën.

Programo sipas interfejsit, jo sipas implementimitSigurohuni se kontratat respektohen.

Klientët shfrytëzojnë interfejsat në mënyrë korrekteImplementuesit implementojnë interfejsat në mënyrëkorrekte (Testoni!)

Dokumentimi i API 4


Përfundim

Programimi ndaj-dhe-pushto (Vazhdim)

. . .Çelësi: dokumentimi i mirë i interfejsit

Problemi i gjuhëve programuese: interfejsi i klasësndërlidhet me pjesën tjetër të definimit të klasës.Nevojitet prezantim i veçantë.API si dokumentacion referencimi

Dokumentimi i API 5


Përfundim

Dokumentimi i kodit burimor

Probleme permanenteShkruarja e API dokumentacionit për një sistem është njëranga punët më të pakëndshme me të cilën do të përballetndonjëherë një zhvillues.

Application Programming InterfacePunë e tipit që mund t’u shpie në dëshprim

Pa dokumentacion −→ pa kodDokumentacioni „joformal“ nuk është standard

Tutorialët, udhërrëfyesit tematikëDuke evoluuar softueri, dokumentacioni „joformal“ dhe kodibëhen të pasinkronizuar!

Më në fund, dokumentacioni bëhet i pashfrytëzueshëm që ebën kodin të vështirë për ta kuptuar dhe për ta përditësuar.

Dokumentimi i API 6


Përfundim

JavaDoc

JavaDoc: Sistem në gjuhën programuese Java përdokumentim kodi dhe prezantim të intefejseve të koditVegla javadoc bën shkrimin dhe mirëmbajtjen epërditësuar të dokumentacionit të kodit më të lehtë!

Vjen me JDKNxjerr dokumentacionin nga komponentat e kodit

Kërkon komente të formatizuara në mënyrë përkatëse

Dokumentimi i API 7


Përfundim

JavaDoc (Vazhdim)

Definon një bashkësi komentesh të formatizuara nëmënyrë të posaçme

Mund të shtohen për të dokumentuar çdopako,klasë (dhe interfejs),metodë, dhefushë

Përdoret për të gjeneruar HTML dokumentacion të klasaveose pakove pas parsimit të komenteve

Dokumentacion ne formatin HTML të APIBazat e HTML: http://www.w3schools.com/html

Dokumentacioni në JavaDoc mbi bibliotekat standarde tëJava:http://docs.oracle.com/javase/7/docs/api/

Dokumentimi i API 8

http://www.w3schools.com/html

http://docs.oracle.com/javase/7/docs/api/


Përfundim

JavaDoc komentet

Menjëherë i paraprijnë komponentës të cilën epërshkruajnëKonsistojnë nga

Përshkrimi i komponentësTë kopjuar siç është në faqen e dokumentacionit

Lista e tagëveTë formatizuar nga javadoc në stil konsistentTë përdorur në klasa, interfejsa, metoda dhe fusha

Dokumentimi i API 9


Përfundim

Formati i JavaDoc komenteve

/*** Fjali përmbledhëse.* Informatë më e përgjithshme mbi* programin, klasën, metodën ose fushën* e cila vijon pas komentit, duke përdorur* sa nevojiten rreshta.** zero ose më tepër tag për të specifikuar* informata të llojit më specifik, si parametrat* dhe vlerat kthyese të një metode.*/

Dokumentimi i API 10


Përfundim

JavaDoc komentet (Vazhdim)

Duhet të jepen për çdo klasë ose interfejs publikDuhet të jepen për çdo metodë ose konstruktor publik



Përfundim

JavaDoc tagët

@author emriEmërton njërin nga autorët e komponentësPërdorni tag të shumëfishtë për më tepër autorëPërdoret në klasë, interfejs, metodë.P.sh., @author Tringa Kosova, lab X

@version versioniIndikon versionin e softuerit që përmban këtë komponentë.Përdoret në klasë, interfejs.



Përfundim

JavaDoc tagët (Vazhdim)

@see cakuDrejto lexuesin nga diçka tjeter relevante për të lexuar, sindonjë klasë tjetër ose metodë specifikeInserton një link i cili pointon nga cakuPërdoret në të gjithaP.sh., @author Tringa Kosova, lab X

@deprecated tekstMarkon një komponentë si të vjetëruar dhe drejton lexuesinnga çfarë të përdorin në vend të saj përmes një @see taguPërdoret në të gjitha



Përfundim

Tagu @see

Drejton nga një tjetër pako, klasë, metodë, fushë osemadje URL

javadoc krijon një linkSintaksa për tekstin pas @see varet prej nga çfarë drejton:

@see pakoja −→ Link nga pakoja@see klasa −→ Link nga klasa në pakon aktuale@see pakoja.klasa −→ Link nga klasa në pakon pakoja@see #metoda −→ Link nga metoda në klasën aktuale@see klasa#metoda −→ Link nga metoda në klasën klasa@see pakoja.klasa#metoda −→ Link nga metoda në klasënklasa në pakon pakoja@see <a href=url>text</a> −→ Link nga URL text



Përfundim

Shembuj

//komponente nga e njëjta klasë@see #field@see#Constructor(Type,...)@see #method(Type, Type,...)

//komponënte nga e njëjta pako@see Class@see Class#field@seeClass#Constructor(Type,...)@see Class#method(Type,...)



Përfundim

Shembuj (Vazhdim)

//komponente nga pako tjetër@see package@see package.Class@see package.Class#field@see package.Class#Constructor(Type,...)@see package.Class#method(Type, Type,...)

//URL@see <a href="spec.html#section">Java Spec</a>



Përfundim


@param parametri përshkrim i shkurtërPërshkruan parametrin parametri të kësaj metodeEvitoni tagun në qoftë se metoda nuk ka parametraPërdorni tag të shumëfishtë për më tepër parametraPërdoret në metodaP.sh., @param size numri i elementëve ne vargun

@return tekstPërshkruan vlerën e kthyer nga kjo metodëEvitoni tagun në qoftë se metoda nuk vlerë kthyesePërdoret në metodaParaqitet pas tagëve @paramP.sh., @return elementin më të madh të vargut



Përfundim

Shembull

/*** Validon një lëvizje shahu.** @author Filan Fisteku* @param theFromLoc lokacioni i figurës që lëvizet* @param theRank rangu i figurës që lëvizet* @param theToLoc lokacioni i fushës së cakut* @return true në qoftë se lëvizja valide, false përndryshe*/boolean isValidMove(int theFromLoc, int theRank, int theToLoc){

//...}



Përfundim


@throws përjashtimi përshkrim i situatës nën të cilënhidhet

Përshkruan përjashtimin përjashtimi të papërpunuarEvitoni tagun në qoftë se metoda nuk hedh përjashtimPërdorni tag të shumëfishtë për më tepër përjashtime, nërenditje alfabetikeParaqitet pas tagëve @param dhe @returnPërdoret në metodaP.sh., @throws FileNotFoundException në qoftë seemri i fajlit jovalid



Përfundim


http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html

http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#javadoctags







Përfundim

Kërkesat minimale

Klasat@author@version

Metodat@param@return@throws



Përfundim

Ekzekutimi i JavaDoc nga vija komanduese

javadoc [opcionet] [pakot] [fajlat]Mund të listohen një ose më tepër pako

Nuk mund të përdoret *

Mund të listohen një ose më tepër java fajlaMund të përdoret *



Përfundim

JavaDoc duke përdorur Eclipse

Code formatterSelektoni kodinSoruce > Format

JavaDoc comment generatorSelektoni projektin ose fajlin në Package ExplorerProject > Generate JavaDoc...Ndiqni magjistarin



Përfundim

Udhëzime për lexim të mëtejmë

http://www.fberisha.org

http://www.w3schools.com/html/





http://www.fberisha.org








Përfundim

Përfundim

API si dokumentacion referencimiJavaDoc komentetJavaDoc tagëtKrijimi i API me anë të JavaDoc


Dokumentimi i API - Naser Kastratinaserkastrati.weebly.com/uploads/3/8/8/3/38831473/docs-06.pdf ·...

Documents

Transcript of Dokumentimi i API - Naser Kastratinaserkastrati.weebly.com/uploads/3/8/8/3/38831473/docs-06.pdf ·...