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

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 .

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.

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.

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.

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 ™.

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 .

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.

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.

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.

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).

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 .

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:

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.