Czy istnieją dobre i nowoczesne alternatywy dla Javadoc? [Zamknięte]

80

Spójrzmy prawdzie w oczy: nie musisz być projektantem, aby zobaczyć, że domyślny Javadoc wygląda brzydko .

W sieci jest kilka zasobów, które oferują zmieniony styl Javadoc. Ale domyślne zachowanie reprezentuje produkt i powinno być odpowiednio ładne.

Innym problemem jest fakt, że użyteczność Javadoc nie jest aktualna w porównaniu z innymi podobnymi zasobami.

Szczególnie duże projekty są trudne do nawigacji przy użyciu szybkiego wyszukiwania Firefoksa.

Pytanie praktyczne:
czy istnieją samodzielne aplikacje (desktopowe), które mogą przeglądać istniejący Javadoc w bardziej użyteczny sposób niż przeglądarka?
Myślę o czymś w rodzaju przeglądarki dokumentacji Mono.

Pytanie teoretyczne:
Czy ktoś wie, czy istnieją jakieś plany ewolucji Javadoc w jakoś ustandaryzowany sposób?
EDYCJA: Przydatne łącze do wiki firmy Sun na ten temat .

ivan_ivanovich_ivanoff
źródło
4
Byłbym szczęśliwy, gdyby javadoc wygenerował prawidłowe strony HTML 4.01 lub XHTML.
akarnokd
2
Jakie masz problemy z użytecznością?
basszero
15
Dlaczego ktoś miałby to głosować? Myślę, że to rozsądne pytanie: +1
Daniel Sloof
2
(X) HTML nie powinien być jedynym sposobem na Javadoc. Przeglądarka jest bardzo ograniczonym narzędziem dostępu do (lokalnej) bazy wiedzy.
ivan_ivanovich_ivanoff
14
Osobiście lubię Javadoc. Jest jasne, zwięzłe i na temat. Z drugiej strony witryna MSDN ...
samoz

Odpowiedzi:

42

Stworzyłem Markdown (java) Doclet, który pobierze komentarze źródłowe w tekście sformatowanym w Markdown i utworzy te same HTML Javadocs.

Nowa dokumentacja również zmienia styl tekstu, ale wygenerowany kod HTML nie jest zmieniany na tym etapie.

To w pewien sposób rozwiązuje problemy z komentarzami HTML-in-java, które są prawdopodobnie największym problemem użyteczności w obecnym Javadoc.

Richard Nichols
źródło
21

Nie sądzę, że koncepcje Javadoc są przestarzałe. O ile wiem, koncepcje te są zakorzenione lata temu w produkcie o nazwie doxygen, który jest nadal dostępny dla innych języków (np. Objective-C, gdzie jest intensywnie używany). Nawet to ma swoje poprzedniczki - spójrz na środowisko programistyczne używane przez Donalda Knutha do tworzenia TeX-a ( programowanie literackie ).

Niemniej jednak intrygującym pomysłem jest posiadanie jednego źródła kodu programu i dokumentacji.

Poza tym prezentację dokumentacji można dostosować do specjalnych potrzeb za pomocą systemu wtyczek obsługiwanego przez narzędzie JavaDoc. Możesz dostarczyć wtyczkę (tak jak my), która publikuje bezpośrednio w bazie danych, która jest bezpośrednio dostępna przez Internet. Korzystając ze współpracy, każdy może przekazać dodatkowe komentarze lub wyjaśnienia do dokumentacji, które mogą znaleźć się w oryginalnym źródle.

Ralf Edmund
źródło
1
Spójrz na ScalaDoc2 scala-lang.org/api/current i powtórz, że Javadoc nie jest przestarzały. :-) Chociaż przyznaję, że to mniej więcej te same podstawowe pojęcia, po prostu DROGA lepsza implementacja. Prawdopodobnie można by zrobić to samo z nową implementacją narzędzia javadoc.
Hans-Peter Störr
13

Javadoc to najlepszy system automatycznej dokumentacji kodu źródłowego, jaki kiedykolwiek widziałem. W dużej mierze to jest takie proste - jeśli chcę, mogę przeglądać javadoc nawet na moim 5-letnim telefonie komórkowym! Chociaż zgadzam się, że odrobina liftingu może być w porządku, a zwłaszcza JDK jest trudnym do przejrzenia, nie odważyłbym się całkowicie wymyślić koła, ponieważ to, co obecnie mamy, to RESTful, łatwe w użyciu rozwiązanie do swojego celu, które działa prawie wszędzie.

Esko
źródło
1
Cóż, z problemem, że linki wewnątrz strony (np. http://download.oracle.com/javase/6/docs/api/java/lang/String.html#String(byte[])) Są nieprawidłowe, ponieważ używają nawiasów, nawiasów i innych znaków, które są niedozwolone. To powoduje ich awarie w niektórych przeglądarkach.
Joey
1
Przy okazji, aktualizacja tego komentarza, obecnie uważam, że scaladoc2 (patrz scala-lang.org/api/current/index.html ) jest w rzeczywistości lepszy niż javadoc, chociaż głównie dlatego, że pożycza dobre części z javadocs, a następnie dodaje kilka innych fajnych rzeczy.
Esko,
2
Kolejna aktualizacja, system javadoc przeszedł gruntowny przegląd w JDK7 i wygląda obecnie dość elegancko, w celach informacyjnych sprawdź oficjalne API javadoc pod adresem download.oracle.com/javase/7/docs/api
Esko
Tak, ale jest TAK Brzydki!
Ziggy,
@Ziggy Stwórz więc własny CSS lub użyj wspomnianego API, aby wygenerować całkowicie unikalną stronę z dokumentacją? : P
Esko
11

Niedawno otrzymałem wiadomość, że Sun pracuje nad modernizacją wyjścia HTML Javadoc. Ze wspomnianej poczty:

Proponujemy ulepszenia javadoc / doclet dla JDK7. Strona wiki projektu znajduje się pod adresem http://wikis.sun.com/display/Javadoc/Home . W ramach proponowanych ulepszeń interfejs użytkownika wyjścia javadoc zostanie odnowiony. Zrzuty ekranu nowego projektu są przesyłane do wiki projektu. Znaczniki wyjściowe javadoc zostaną zmodyfikowane, aby były zgodne z HTML i WCAG 2.0.

Tak więc z pewnością nadal trwają tam prace, nawet jeśli jest trochę późno. Jednak moim zdaniem jedną z największych wad Javadoc jest jego bardzo ścisłe powiązanie z HTML. Wiele klas ma Javadoc, który zawiera dosłowny HTML i opiera się również na HTML. Niefortunne, ale myślę, że to się nigdy nie zmieni. Niemniej jednak oznacza to, że programiści mogą dowolnie umieszczać tam, co chcą, w HTML, co równie dobrze może być nieprawidłowe, źle sformułowane itp. Zatem dostosowanie danych wyjściowych z narzędzia javadoc to tylko jedna część tego, druga wygrana t i nie może się zmienić, a zatem pozostaje.

Jeśli chodzi o przeglądanie dokumentacji, to również dokumentacja HTML jest trochę nieporęczna. Zwykle używam widoku Javadoc w Eclipse. Ma również wady (powolne i nie można naprawdę wyszukiwać), ale w większości przypadków jest wystarczająco dobre ™.

Joey
źródło
DOBRE WIEŚCI !!! DZIĘKUJĘ CI !!! Zmienię teraz moje pytanie, aby udostępnić ten przydatny link.
ivan_ivanovich_ivanoff
@ivan_ivanovich_ivanoff, być może mógłbyś również wyrazić swoje obawy z zespołem Sun. Wygląda na to, że jeśli mogą cię uszczęśliwić, przyniesie to korzyści nam wszystkim.
Thorbjørn Ravn Andersen
5

Osobiście nadal uważam Javadoc za bardzo przydatny. Zwłaszcza, że ​​jest znormalizowany. Nie znam żadnego głównego stylu dokumentacji, który wydaje mi się łatwiejszy w nawigacji (może to być bardzo subiektywne, ale osobiście uważam, że MSDN jest na przykład okropny).

Do wyszukiwania: użyj ramki wyszukiwania Javadoc , znacznie ułatwia korzystanie z wszelkiego rodzaju Javadoc. Jest dostępny jako skrypt użytkownika dla przeglądarki Firefox i jako rozszerzenie Google Chrome .

Joachim Sauer
źródło
1
Wydaje mi się, że ramka wyszukiwania Javadoc wyszukuje tylko nazwy pakietów i klas w ramce po lewej stronie, co jest przydatne, ale nie jest tak przydatne, jak byłoby to wyszukiwanie pełnotekstowe.
Glenn Lawrence
4

Aby odpowiedzieć na Twoje praktyczne pytanie, wyszukałem w Google i zapytałem znajomych i wymyśliłem je. Forrestdoc, doclet i doxygen.

Drugie pytanie, powiedziałbym, że tak, to nie jest zbyt „Web-oh-twoeye”, ale przynajmniej gwarantujesz, że będziesz pracować w środowisku offline i jest wystarczająco mały, aby był dostarczany wraz z twoim API. nie używam ramek, ale działa to raczej dobrze w przypadku javadoc. Nie widziałem żadnych planów, aby to zmienić. Eclipse ma pewne wsparcie dla javadoc, jeśli chodzi o czytanie, interpretowanie i generowanie.

Gerrie
źródło
3

Możesz wyrazić to w mniej agresywny i apodyktyczny sposób. Większość ludzi nie przejmuje się wyglądem zasobów technicznych i „To za mało Web 2.0!” brzmi jak nudny marketroidspeak.

A co dokładnie uważasz za „bardziej użyteczne”? Osobiście na pewno chciałbym mieć wyszukiwanie pełnotekstowe i lepszą przeglądarkę użytkową, a AJAX prawdopodobnie mógłby w tym pomóc.

Cóż, fajną rzeczą w JavaDoc jest to, że jest przeciwieństwem przestarzałej - jest dowolnie rozszerzalna. Dlaczego nie pójść dalej i napisać doclet który wytwarza rodzaj API doc chcesz?

Nikt nie zgaduje, dlaczego nikt inny tego nie zrobił (co najwyraźniej tak jest) - może nikt inny nie czuje tego tak mocno jak Ty.

Michael Borgwardt
źródło
1
1) Faktem jest, że ludzkie wrażenie użyteczności zależy od dobrego projektu. 2) AJAX - dla lokalnego pliku: // zasób? 3) Jestem pewien, że nikt w ekosystemie C / C ++ nie czuje się tak mocno związany ze spójnym nazewnictwem jak ja, ale to nie unieważnia potrzeby spójnego nazewnictwa.
ivan_ivanovich_ivanoff
2
1) Co dokładnie uważasz za „dobry projekt”? Po pierwsze, uważam, że zwykły JavaDoc jest dobrze zaprojektowany. 2) Przypuszczam, że nie byłby to prawdziwy AJAX, ale podobna funkcjonalność powinna być faktycznie możliwa. 3) Mimo to wygląda na to, że obecny JavaDoc jest wystarczająco dobry dla większości ludzi, że nikt nie zadał sobie trudu, aby stworzyć lepszy - co nie byłoby wcale takie trudne.
Michael Borgwardt
1
1) Część standardowa: dane o silnej strukturze, a nie HTML. Część wdrożeniowa: aplikacja komputerowa napisana w Javie;) 3) Myślę, że można by znaleźć wielu ochotników do ulepszenia Javadoc, ale aby uczynić go poważnym, potrzebny byłby JSR. Nierealne do osiągnięcia w tym temacie.
ivan_ivanovich_ivanoff
@ivan_ivanovich_ivanoff: Jak myślisz, które dane o silnej strukturze są potrzebne? A dlaczego by nie napisać javadoc-doclet, który tworzy taki format? I absolutnie sprzeciwiam się idei aplikacji komputerowej, ponieważ blokuje ona dostęp do określonej aplikacji, aby wyświetlić dokumentację.
Mnementh
2

Jest dokumentacja DocBook. DocBook to bogatszy typ dokumentu niż (X) HTML i lepiej nadaje się do opisywania treści technicznych. Ze źródła DocBook możesz generować różnego rodzaju formaty wyjściowe.

Nat
źródło
2

Osobiście chciałbym mieć bardziej czytelny standard „dokumentacji komentarzy” niż HTML (i stąd znacznik-wieldy) JavaDoc.

Na przykład, MarkDown, w użytym tutaj znaczeniu, byłby doskonały, czytelny dla człowieka w źródle, ładnie sformatowany poza źródłem.

Przy obecnym JavaDoc wyobrażam sobie, że wiele osób używa komentarzy JavaDoc, ale tak naprawdę nie dokumentują w takim stopniu, w jakim mogliby. Jestem pewien, że wszyscy przeglądali online JavaDoc API, która nie została udokumentowana lub ledwo udokumentowana, a zatem jest o wiele trudniejsza w użyciu niż powinna.

Nie pomagają w tym zmiany w kodzie (np. W Eclipse lub po zatwierdzeniu źródła), które całkowicie niszczą każdą czytelną strukturę, którą mógłbyś umieścić w komentarzu JavaDoc (np. Listę elementów) w jeden duży fragment tekstu, chyba że dosłownie użyjesz dwóch powrotów karetki, gdzie chcesz użyć jednego).

JeeBee
źródło
2

Czy ktoś wie, czy istnieją jakieś plany ewolucji Javadoc w jakoś ustandaryzowany sposób?

Odpowiedni JSR (JSR 260), który określa ulepszenia Javadoc, został odrzucony z JDK 7 (na razie). Przegląd tego, co zostało zaplanowane (z tej strony ):

Zaktualizuj Javadoc, aby zapewnić bogatszy zestaw tagów, aby umożliwić bardziej uporządkowaną prezentację dokumentacji Javadoc. Ten JSR obejmuje: kategoryzację metod i pól, semantyczny indeks klas i pakietów, rozróżnienie metod statycznych, fabrycznych, przestarzałych od metod zwykłych, rozróżnienie metod dostępu do właściwości, łączenie i dzielenie informacji na widoki, osadzanie przykładów i typowych przypadków użycia, i więcej.

Ogólna perspektywa dla JDK 7 jest dość ponura .

pmf
źródło
1

JavaDoc jest sama w sobie niezwykle elastyczna, ponieważ standardową dokumentację można zastąpić niestandardową dokumentacją, aby zapewnić coś, co spełnia określone potrzeby projektu.

W ramach projektu, nad którym pracowałem, stworzyliśmy system dokumentacji oparty na HTML / XML (używając XSLT 2.0 po stronie klienta w JS) dla naszego produktu z całkowicie zintegrowanym JavaDoc. W tym celu wykorzystano niestandardową dokumentację do tworzenia danych JavaDoc w formacie XML, która wykorzystała grupę tagów, aby zapewnić, że nawet znaczniki HTML w komentarzach do kodu były dobrze sformułowane.

Dzięki temu byliśmy w stanie zapewnić interaktywne wrażenia użytkownika za pomocą aplikacji jednostronicowej (podobnej do narzędzia komputerowego), ale wszystko z poziomu przeglądarki - bez żadnego kodu / infrastruktury po stronie serwera. Przeglądarka zawiera standardowe funkcje, takie jak wyszukiwanie, nawigacja po drzewie itp.

Oto łącze do przykładowego punktu wejścia w dość obszernej dokumentacji: przykład przeglądarki JavaDoc

Tutaj jest również obraz: wprowadź opis obrazu tutaj

pgfearo
źródło
0

Inteligentna przeglądarka javadoc z możliwością wyszukiwania:

Wielokrotnie mam problem z przeglądaniem JavaDoc. Szukałem czegoś podobnego do opcji wyszukiwania dokumentów Adnroid. Nareszcie coś takiego dostaję. Jeśli używasz przeglądarki Firefox, rozwiązanie jest tutaj.

  1. Zainstaluj wtyczkę GreaseMonkey, jej rodzaj dostosowywania strony internetowej tak, jak widzimy. (Musimy dostosować każdą stronę dokumentacji java, abyśmy mogli wyszukiwać według nazwy klasy) https://addons.mozilla.org/en-US/firefox/addon/greasemonkey/

  2. Aby greasemonkey działał, potrzebujemy skryptu użytkownika do dostosowania. Można to pobrać automatycznie przez greasemonkey. Zainstaluj skrypt użytkownika z ramki wyszukiwania JavaDoc lub wyszukiwania przyrostowego JavaDoc .

To działa świetnie dla mnie.

karim
źródło