javadoc -d html pakiet - Fatcat - AGH

JavadocGenerowanie dokumentacji API

javadoc• Narzędzie ułatwiające pisanie dokumentacjitechnicznej programu (interfejs programisty)• Standardowo przetwarza automatyczniekomentarze na dokumenty HTML• Doclety pozwalają na tworzenie dokumentacji winnych formatach

Zalety• Dokumentacja zmieniana razem z kodem• Można tworzyć dokumentację nawet bez gotowychimplementacji• Dokumentacja w różnych formatach

Możliwości• Lista wszystkich pakietów• Lista wszystkich klas w poszczególnych pakietach• Hierarchia klas w pakiecie• Hierarchia i zależności między klasami w różnychpakietach• Użycie pakietu• Opisy dla każdej klasy, interfejsu i pakietu• Informacje o przestarzałym API• Alfabetyczny spis klas, interfejsów, konstruktorów, póli metod

Podstawy/** Komentarz dla klasy */public class MojaKlasa {/** Komentarz dla metody */public int Metoda() {return 1; }}/** Komentarz dla zmiennej */protected String napis;

Podstawy

Podstawy• Domyślnie javadoc przetwarza tylko składowepubliczne i chronione• Przykład – http://java.sun.com/j2se/1.5.0/docs/api/• Dodawanie komentarzy do pakietów – plik packageinfo.java:/** Komentarz dla paczki */package moja.paczka

Znaczniki dokumentacyjne - ogólne• @author autor• @version wersja• @see klasa (ew. klasa#metoda, info)• {@link klasa#metoda etykieta}• @deprecated• {@docRoot}• {@inheritDoc}

Znaczniki dokumentacyjne dla metod• @param parametr opis• @return opis• @throws wyjątek opis• @exception wyjątek opis

Uruchamianie• Manual– javadoc lub javadoc –help• Generowanie dokumentacji– javadoc [opcje] nazwa_pakietu– javadoc [opcje] nazwa_pliku.java

Opcje­overview ­public­protected­package­privatetylko klasy public i ich składowedodatkowo klasy protectedjw + klasy widoczne w pakieciedokumentacja dla wszystkich klasi składowych

Opcje-doclet nazwa_pliku-docletpath -sourcepath -classpath plik klasowy z docletemdo pliku .class docletudo plików źródłowychdo plików .class-exlude -subpackages pakiety wykluczonerekurencyjnie-encoding kodowanie pliku źródłowego

DocletyDoclet jest oddzielnym programem napisanym w językuJava, z API docletu, który określa zawartość i format plikuwyjściowego, który ma być wygenerowany przez Javadoc.Przykład użycia:javadoc -docletJP.co.esm.caddies.doclets.UMLDoclet -private*.java

Standardowy doclet-d katalog – katalog docelowy-version – uwzględnia znacznik @version-author – uwzględnia znacznik @author-splitindex – dzieli index wg liter alfabetu-use – informuje o uzyciu klas-nodeprecated – ukrywa @deprecated-noindex – nie generuje indeksu-notree – bez hierarchii klas-nohelp – bez strony pomocy

Standardowy doclet-header - nagłówek dla każdej strony-bottom - wstawia kod na dole strony-footer - stopka-docencoding - nazwa kodowania-charset - użyty zestaw znaków

Własny docletimport com.sun.javadoc.*;public class KlasaWypisz{public static boolean start(RootDoc root){classDoc[] klasy = root.classes();for (int i = 0; i , klasy.length; ++i){System.out.println(klasy[i]);}}}

Ćwiczenie•Rozpakować załączony projekt i uruchomić wewnątrz kataloguProjekt. Porównać wynik ze strukturą projektu i treściąkomentarzy:•javadoc -d html pakiet•javadoc -d html -subpackages pakiet•javadoc -d html -subpackages -public pakiet•javadoc -d html -subpackages -protected pakiet•javadoc -d html -subpackages -package pakiet•javadoc -d html -subpackages -private pakiet•javadoc -d html -overview ./overview.html -charset "utf-8"-author -subpackages pakiet -package• Dodać własne komentarze:­ atrybutu prywatnego ­ Klasa.intAtr­ metody ­ Klasa.metoda­ metody ­ KlasaPackage.metodaWyjatkowa

javadoc domyslnie przetwarza tylko skladowe public i protected(tylko te widzi uzytkownik), pakietowe i chronione ­opcjainfo o calej aplikacji (zestawie papkietow) w plikuoverview.html@link ­ zamiast see also (@see) widac etykietejavadoc ­d html pakiet ­overview ./overview.html ­docencoding"utf­8" ­charset "utf­8"

DoxygenNarzędzie do automatycznegogenerowania dokumentacji

DoxygenDoxygen ­ generator dokumentacji dla języków C++, C,Java, Objective­C, Python, IDL i do pewnego stopnia dlaPHP, C#, D oraz ActionScript.Doxygen jest tworzony dla systemu Linux i Mac OS woparciu o bibliotek, e Qt. Dostępny również w wersjibinarnej na WindowsDoxywizard ­ graficzna aplikacja ­ ułatwia tworzeniepliku konfiguracyjnego dla dokumentacji danego projektu.

Formaty wyjścioweObsługuje on następujące formaty wyjściowe: HTML,CHM (format plików pomocy Windows), RTF, PDF,LaTeX wraz z Makefile, PostScriptStrony man

Sposoby komentowania koduAby wygenerować dokumentację przy pomocy programuDoxygen należy wczesniej odpowiednio zakomentować kod.Można to zrobić na kilka sposobów:1. Komentarze wielolinijkowe/****Komentarz**//*!**Komentarz**/

Sposoby komentowania kodu cd.Gwiazdki przed tekstem komentarza są opcjonalne,komentarze można zapisać tak:/**Komentarz*//*!Komentarz*/2. Komentarze jednolinijkowe (przed lub za treścią komentarzamusi znaleźć sie przynajmniej jeden pusty komentarz)://////Komentarz/////!//!Komentarz//!

Znaczniki komentarzyW komentarzach można używać specjalnych znacznikówzaczynających się od @ lub\:@mainpage – dodaje tekst na stronę główną@brief – skrócony opis funkcji/klasy@author XYZ – Dodanie sekcji Autor@date 2006.12.12 – Dodaje sekcję Data@version 1.0 – Dodaje sekcję Wersja@attention text – Dodaje sekcję Uwaga i wpisuje tam text@return text – opis wartości zwracanych przez funkcję@image format filename – dodaje plik graficzny

Znaczniki komentarzy cd.@class – oznacza, że dokumentowana będzie klasa @fn­ oznacza, że dokumentowana będzie funkcja@par – tworzy nowy paragraf z dokumentacją@par tytul – j.w. Z tytułem 'tytul'@param nazParam Opis ­ Opis parametrówprzyjmowanych przez metodęChcąc użyć w dokumentacji któregoś ze znaków: $,@, \, &, ~, , #, %, musimy zastosować backslash (\).

Tworzenie pliku konfiguracyjnegoOd pliku konfiguracyjnego zależy, jak będziezachowywał się Doxygen przy generowaniu dokumentacji.Plik konfiguracyjny można stworzyć na trzy sposoby:Wygenerować go korzystając z opcji "Wizard..." programuDoxywizard,Skorzystać z opcji "Expert..." Doxywizard,Stworzyć go w linii poleceń na podstawie wzorcowego plikukonfiguracyjnego.

Doxywizard: WizardDoxywizard uruchamiamy poleceniem:user@fatcat:~$ doxywizardnastępnie tworzymy plik konfiguracyjny w 4 prostych krokach:Krok 1: Klikamy opcję ”Wizard” i podajemy kilka informacji oprojekcie: nazwę, wersję, ścieżki do kodów źródłowych. Jeśli plikiźródłowe projektu znajdują się w drzewie katalogów należyzaznaczyć opcję ”Scan recursively”

Doxywizard: Wizard cd.Krok 2: Po ustawieniu opcji z kroku poprzedniego klikamy ok izapisjemy plik konfiguracyjny o domyślnej nazwie DoxyfileKrok 3: Wybieramy katalog roboczyKrok 4: Generujemy dokumentację uruchamiając Doxygenaprzyciskając przycisk ”Start”. Czekamy chwilę na informację :"*** Doxygen has finished".To wszystko dokumentacja została wygenerowana.

Konfiguracja w linii poleceńKonfiguracja na podstawie wzorcowego pliku konfiguracyjnego.Wzór pliku konfiguracyjnego tworzymy poleceniem:user@fatcat:~$ doxygen.exe -gnazwaPlikuConfbądź samym:user@fatcat:~$ doxygen.exe -gwtedy wzór zostanie zapisany pod domyślną nazwą "Doxyfile".

Konfiguracja w linii poleceń cd.Następnie należy wyedytować ten plik i pozmieniać zapisanew nim opcje według uznania (w większości przypadków sprowadzasię to do wpisania przy opcji słowa "YES" bądź "NO").Aby wygenerować dokumentację wydajemy polecenie:bądź samouser@fatcat:~$ doxygen.exe nazwaPlikuKonfiguracyjnegouser@fatcat:~$ doxygen.exejeśli nasz plik nazywa się "Doxyfile".

Parametry KonfiguracjiOpcje projektu:PROJECT_NAME – nazwa projektuPROJECT_NUMBER – wersja projektuOUTPUT_LANGUAGE – język dokumentacjiOUTPUT_DIRECTORY – katalog wyjściowy dokumentacjiEXTRACT_ALL – określa czy funkcje i składowe które nie mają opisuw kodzie źródłowym mają się znaleźć w dokumentacji

Parametry KonfiguracjiOpcje procesu tworzenia dokumentacji:QUIET – włącza/wyłącza komunikaty DoxygenaWARNING – włącza/wyłącza ostrzeżeniaWARN_FORMAT – pozwala określić format ostrzeżeńOpcje dotyczące plików:INPUT – pliki źródłowe na podstawie których generujemydokumentację, może być katalogFILE_PATTERN – filtruje pliki na podst. wyrażeń regularnychRECURSIVE – czy dołączać pliki z podkatalogów

Doxywizard: ExpertStanowi jedynie graficzny interfejs, który pozwala w łatwysposób edytować plik Doxyfile.

Prosty przykład generowaniadokumentacjiOto fragment pliku zakomentowanego w sposób ”czytelny” dlaDoxygena dla którego generuje on dokumentację:/*** @mainpage* @author User* @date 2008.11.13* @version 1.0*/#include#includeusing namespace std;/****\class UL*@brief Klasa przechowujaca ulamek**l i m to 2 zmienne typu int reprezentujace licznik i mianownik ulamkow*@n uzywanych do sumowania w funkcji main zapomoca przeladowanego operatora '+'*/class UL{private:int l;int m;public:...

ĆwiczeniePobrać cały plik którego fragment zamieszczono napoprzednim slajdzie i wygenerować dla niego dokumentacjęużywając programu Doxygen (Doxywizard).Plik znajduje się pod adresem:http://fatcat.ftj.agh.edu.pl/~i6gozdur/IO/dok2/ulamki.cppMożna ją porównać z dokumentacją w HTML, którąwygenerowano wczesniej:http://fatcat.ftj.agh.edu.pl/~i6gozdur/IO/dok2/html/

Zadanie1. Edytować jeden ze swoich plików źródłowych.2. Dodać do niego komentarze pozwalające wygenerowaćdokumentację przez Doxygen.3. Wygenerować dokumentację na wszystkie 3 możliwe sposobytzn: Doxywizard Doxywizard→→WizardExpertZ linii poleceń

LinkiPoniżej podaję kilka linków które mogą być pomocne w wykonaniudokumentacji:Strona Główna Doxygena:http://www.doxygen.org/Doxygen – wprowadzeniehttp://icis.pcz.pl/~agrosser/test/doxygen.pdfGenerowanie dokumentacji w Doxygen'iehttp://grafit.mchtr.pw.edu.pl/~mozaryn/ZAP/ZAP2/zap_2_03.pdf