ZPP

Do pojutrza każdy niech opracuje sobie ogólną koncepcję nt javadoców - co chciałby pokazać, co mu się w tym podoba, a co nie itd. Pojutrze wieczorem zbiorę to wszystko i podzielę pracę. Będziemy mieli prawie tydzień, więc jak się sprężymy, to wyjdzie coś fajnego. pzdr

W temacie javadoców chyba ciężko o wielkie fajerwerki. Ciężko mi powiedzieć tak naprawde,
co mi sie w tym podoba, a co mi sie nie podoba- nie używałem tego do tej pory. Tym niemniej
pare rzeczy mi się nasunęło(szkoda, że to głównie ogólniki):
-fajna jest sam pomysł automatycznego generowania dokumentacji, nie trzeba się martwić
o jakieś układ stron, formę graficzną itd.
-ułatwiają komunikacje pomiedzy programistami- nie trzeba szukac wszystkiego w kodzie, tylko
można wygenerować dokumentacje i w wygodny sposób poszukać czegoś tam, ma się klasę, metody
i ich opisy w jednym miejscu, można abstrahować od kodu
-można jakoś modyfikować wygląd naszej dokumentacji (można podać css, na którego podstawie
ma być wygenerowana dokumentacja)
Co mi sie nie podoba(a przynajmniej co mogłoby być w jakiś sposób poprawione):
-dokumentacja tylko jako html(pdf, ps i inne takie rzeczy chyba były jakoś testowane, ale zdaje
się, że jeszcze nie do końca działają)
-nie można dokumentować treści metod

To co wg mnie należaloby powiedzieć:
-co dokładnie generuje javadoc(liste pakietów z klasami, hierarchie klas i zależności miedzy nimi
opis klas, pakietów, metod, przestarzałe metody, indeks)
-może coś o docletach(co to jest; że można napisac własny; jak używać niestandardowych docletów)
-jak korzystać z javadoc(tzn. gdzie i jak to umieszczać w kodzie; znaczniki- co to, jakie są
i co znaczą)
-jak uruchomić javadoc(tzn juz samo tworzenie dokumentacji) w eclipse(tam jest łatwo) NetBeansie
(tu nie wiem), coś o opcjach(public, protected, private itd.)

To by było na tyle, moze nie jest tego jakos strasznie duzo, ale na 15 minut na pewno wystarczy,
a chyba więcej ciężko byłoby wymyslić.
pozdro

Przydatne linki:
[1] http://www.mimuw.edu.pl/~janusz/dydaktyka/2004-2005/info_zpp/prezentacje/javadoc/index.html
[2] http://java.sun.com/j2se/javadoc/writingdoccomments/
[3] http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/doclet/overview.html

Jak widze prezentacje z javadoc:
Podoba mi sie [1], choc skupilbym sie na eclipsie, a javadoc z konsoli zostawilbym na koniec, jakby zostal czas(mozna sprobowac pokazac wzajemna jednoznacznosc lub jej ewentualny brak). Mysle, ze warto by powiedziec o stylu pisania javadocow i tu mozna by sie oprzec na [2]. Mozna by tez pokazac korzystanie z niestandardowego docletu przyklady mozna znalezc w [3]. No i wszystko oparte na przykladach klikanych na ekranie. Mysle, ze mozna by sie posluzyc xvidcap'em (ewentualnie hypercamem pod winda), zeby pozniej wyslac ludziom filmik, bo z ogladania klikania na zajeciach malo zostaje w pamieci.

Teraz coś ode mnie. Jak dla mnie w javadocach zawsze podobało mi się to, że ktoś za mnie robił całą czarną robotę związaną z dokumentacją. Spędza się chwilę na nauce poprawnej obsługi tego narzędzia, po czym nie trzeba pisać oddzielnych plików readme i innych tego typu głupot. Wprowadza sporo porządku. Lubię tego typu standardy, bo są w miarę jednolite - co z tego, że ktoś inny wymyśli równie dobry standard dokumentowania kodu, jeśli ja będę musiał stracić na jego naukę kolejne dwie godziny. Największy problem miałem ze współpracą tego z ide. Często można się pogubić w folderach z dokumentacją itd. Pamiętam, że na początku zajęło mi sporo czasu dogranie tego z ide i częściowo pracowałem zupełnie bez sensu z dokumentacją braną z neta. Jeśli chodzi o naszą prezentację, to proponuję następujący podział:
Paweł - integracja javadoca z Netbeansem
Sławek - to samo z Ecclipse
Przy tych integracjach oczekuję rzeczy w stylu: automatyczne dostawianie komentarzy na podstawie wklepanego kodu klasy/metody, narzędzia do obsługi javadoców, jeżeli coś takiego jest, to też podglądanie dokumentacji w trakcie pisania kodu no i generalnie wszystkie featursy będące wsparciem ide dla javadoców)
Karol - jak to się robi spod konsoli + zmiana standardowego wyglądu javadoca css'em (tu chodzi mi o krótki i chwytliwy przykład - jakiś prosty, ładny szablon; najlepiej, żeby to się dało podmienić za pomocą kilku kliknięć myszą i/lub wpisaniu ścieżki do css'a)
Ja zajmę się maven javadoc pluginem i stylem pisania tagów
Jako, że ostatnio ja nic nie referowałem, to tą prezentację poprowadzę w całości. Wasze zadanie ma charakter praktyczny, więc proszę o konkretne zastosowania, najlepiej z podanym przykładowym kodem, na którym można to będzie później pokazać reszcie grupy. Nie chcę dublować Waszej pracy, więc wytyczne mają być w deseń: "Tu klikamy na plik/zapisz... itd", tak żeby przeciętny orangutan zrozumiał. Pomyślę nad opracowaniem tego w jednym z narzędzi, o których pisał scravek. Może to wyznaczy jakiś nowy trend na zajęciach
Tymczasem pozdrawiam,
P.

Następnym razem dla jasności będę wpisywał szczegółowe deadline'y w nazwach tematów. Termin tego zadania wyznaczam na niedzielę, przy czym załóżcie, że będzie to niedziela rano, np. do 11. Nie wiem dokładnie, o której w niedzielę wrócę do Wawy. Początkowo niech każdy zamieści materiały na svnie w katalogu trunk/pr-javadoc . Jeśli będę głupszy niż przeciętny orangutan, to będę pisał do każdego indywidualnie

Tylko kwestia javadoc w Netbeans jest rozwiązana z tego co widze strasznie po łebkach albo ja nie mam kumy.
Bo jest coś takiego jak Build -> Generate Javadoc i już, bez żadnych kreatorów.
Ewentualnie można włączyć:
Tools -> Options -> Java Code -> Hints -> Javadoc
ale to średnio aspiruje do miana narzędzia, bardziej hint jak sama nazwa wskazuje
[edit] Po mkrótkich konsultacjach z osobą która już w javie coś robiła mam takie wieście: w 6.1 nie wiadomo co jest ale dzisiaj (albo wczoraj) wyszła wersja 6.5 więc trzeba tam obadać czy to nie wróciło
Będe wiedział najpóźniej w sobote bo kolega ma spotkanie z kolesiami od netbeans'a.

Co do Eclipsa to tez za duzo tu nie ma, choc moze jeszcze za malo poszukalem. Fajne na pewno jest Shift+Alt+J co generuje szkielet komentarza, ktory jeszcze mozna sobie samemu ustawic do wlasnych potrzeb. No to to moge jakos przygotowac.

Mam jeszcze pytanko co do samego javovego kodu - Mysle, ze dobrze byloby zrobic wspolny (nieduzy) kod taki powiedzmy, zeby byly jakies sensowne metody, stale i podklasy i na tym jednym kodzie, zeby byly wszystkie przyklady. Moge wrzucic jakis taki kod na svna, ktory tam mozna bedzie w miare checi modyfikowac

(/trunk/Slawek/javadoc.zip)

Ok Sławek - wrzuć jakiś przykładowy kod i każdy będzie go modyfikował w zależności od tego, co jeszcze chce pokazać.

To ja się podziele wrażeniami z NetBeans'a 6.5:
W sumie jakiś super rozbudowanych rzeczy nie ma
Na pewno fajnym skrótem jest
/** + ENTER
napisany przed metodą który generuje gotowy szablon z metodami itp. dla javadoc i się tylko uzupełnia jak ankietę
jakby ktoś chciał dołożyć coś własnego to po wciśnięciu małpy w zasadzie dostaje listę tego co może jeszcze dodać.
Generatora żadnego nie widze
Potem jest Z projektu wybierasz dobrą aplikację -> Prawy myszy -> Generate Javadoc
Co do jakiegoś sprytnego add-on'a czy funkcjonalności to generującej to jeszcze nic nie wiem

Tu jest ten link o którym rozmawialiśmy:
http://netbeans.dzone.com/news/javadoc-analyzer-netbeans-61