Czytanie dokumentacji

Pojawiały się prośby o to, aby opisać sposób przeglądania i korzystania z dokumentacji, więc czas najwyższy wam w tym pomóc.

Zacznijmy od tego, czym właściwie jest dokumentacja. Jest to instrukcja użytkowania klas przedstawiana w przejrzystej formie, która ma pomóc programiście w korzystaniu z gotowych rozwiązań. Dokumentacje są tworzone zarówno do standardowych bibliotek języka, jak i tych stworzonych przez użytkowników - środowiska takie jak eclipse, czy netbeans posiadają gotowe pluginy, dzięki którym dokumentacja zostanie wygenerowana automatycznie na podstawie komentarzy dokumentujących.

Szukanie przez Google

Jako przykład weźmy klasę JComponent - ponieważ posiada ona wszystko to na co warto zwracać uwagę. Najłatwiej będzie ją odnaleźć po prostu wyszukując ją w google (ja zazwyczaj tak robię). Można również pobrać ją w wersji offline. Wpisujemy więc w google "jcomponent java" i szukamy.

Prawie zawsze będzie to wyglądało jak na obrazku powyżej. Na 2 pozycji pojawił się dodatkowo link prowadzący do tutoriala oracle na temat Swinga. Nas interesują przede wszystkim 1 i 3 wynik. Różnią się one tym jakiej wersji javy dotyczą - ponieważ wraz z jej aktualizacjami wiele klas było poprawianych. Przykładowo w dawnych wersjach w wielu przypadkach nie były stosowane settery i gettery, które później zostały dodane - jest to bolączka szczególnie w programowaniu niektórych urządzeń w technologii J2ME, które posiadają mocno ograniczone możliwości. Stosuje się tam często okrojone biblioteki, na przykład z wersji Java 1.1 i wiele rzeczy tam po prostu jeszcze nie było - trzeba je dopisać samemu.

Wracając do tematu, na powyższym obrazku widzimy 2 wersje klasy: w wersji 1.4 i wersji 6 (co ciekawe do wersji 1.5 były one dokładnie takie jak napisano - tzn 1.1, 1.2 itd, natomiast wersjie 1.6 i 1.7 określane są już jako 6 i 7). Wejdźmy najpierw w jeden z linków - najlepiej wersję najnowszą, w tym przypadku 6.

Dokumentacja

Hierarchia dziedziczenia i powiązane klasy

Na samej górze widać hierarchię dziedziczenia - jak wiadomo wszystkie klasy w języku Java dziedziczą z klasy Object, więc zawsze to ona będzie na szczycie (oprócz samych nazw widać też pakiety, w których się znajdują). Nieco niżej znajdują się wszystkie implementowane przez daną klasę interfejsy. Zazwyczaj znajdą się tutaj interfejsy odpowiedzialne za serializację (Serializable), w niektórych przypadkach Comparable przydatny przy porównywaniu (np. przy sortowaniu danych). Jeszcze niżej są wszystkie klasy, które dziedziczą z przeglądanej klasy (czyli u nas JComponent) - jak widać może być tam tego naprawdę sporo.

Dalej znajduje się opis klasy - jej zastosowanie i szczegóły na które powinniśmy uważać. Jest to szczególnie ciekawy fragment w przypadku klas niestandardowych bibliotek - niestety zazwyczaj najczęściej tam pomijany. Czasami znajdziemy tam mini przykłady wykorzystania, a dodatkowo zmiany w stosunku do poprzednich wersji. Warto szczególną uwagę zwracać na fragmenty oznaczone jako Warning. W przypadku klasy JComponent dowiadujemy się tam przykładowo, że pakiet Swing nie jest Thread Safe (nie wiem jako to sensownie na nasz język przetłumaczyć, ale chodzi o to, że wszystkie akcje wykonywane na obiektach pakietu Swing związane np z aktualizacją wyglądu okien powinniśmy wykonywać poprzez wątek dystrybucji zdarzeń).

Pola, konstruktory i metody

Dalej zaczyna się najbardziej użyteczna część: spis klas wewnętrznych, konstruktorów, pól i metod. Pierwsze z wymienionych pominiemy z tego względu, że każda z nich posiada swoją własną dokumentację - w przypadku JComponent widzimy JComponent.AccessibleJComponent (oraz klasy wewnętrzne związane z dziedziczeniem - patrz hierarchia dziedziczenia z początku).

Field Summary - jest to tabelka zawierająca wszystkie dostępne dla nas pola klasy. Zazwyczaj będą to jakieś stałe, lub pola statyczne. W przypadku klasy JComponent nie ma tam specjalnie ciekawego przykładu, ale na przykład w klasie BigInteger odnajdziemy już najczęściej wykorzystywane stałe BigInteger.ZERO, czy BigInteger.ONE, oznaczające odpowiednio wartości 0 i 1.

Constructor Summary - tabelka zawierająca wszystkie dostępne konstruktory. W przypadku klasy JComponent jak widać istnieje tylko jeden konstruktor, który nie przyjmuje żadnych parametrów.

Method Summary - tabelka zawierająca wszystkie metody danej klasy. Jest to część, z której najczęściej się korzysta - można tutaj zobaczyć jakie parametry przyjmuje metoda, dodatkowo w formie jednego zdania opisane jej działanie. Jeżeli klikniemy na którąś z nich zostaniemy przeniesieni niżej do jej szczegółowego opisu, gdzie znajdziemy informacje od której wersji Javy jest ona dostępna, co zwraca w konkretnych przypadkach i jakie zgłasza wyjątki. Lewa część tej tabelki pokazuje co dana metoda zwraca w wyniku, po prawej jakie przyjmuje parametry (niektóre z nich będą posiadały kilka wersji z różnymi parametrami). Warto zwracać uwagę na oznaczenie Deprecated - oznacza to, że użycie danej metody nie jest zalecane.

Kilka linijek niżej znajduje się także coś takiego jak Methods inherited from class - czyli metody odziedziczone z klas wyższego rzędu (ponownie patrz na początek). I to w zasadzie tyle, poniżej jeszcze kilka uwag.

• Raczej nie warto zaprzyjaźniać się bliżej z taką wersję przeglądania dokumentacji. W środowisku typu eclipse wpisz nazwę klasy, wciśnij ctrl+Spacja, wyświetli Ci się chmurka z podpowiedziami danej klasy, oraz klasami rozpoczynającymi się od takiego samego słowa. Po pojedynczym kliknięciu na którąś z nich otrzymasz dokumentację w mini wersji.
• Po ostatniej aktualizacji Javy do wersji 7 zmienił się wygląd na bardziej nowoczesny (mi przypomina wersję Api Androida)

Linki

• Dokumentacja Java 7
• Dokumentacja Android