Javadoc: package.html lub package-info.java

230

Kiedy próbujesz utworzyć komentarze Javadoc na poziomie pakietu, jaka jest preferowana metoda? Co robisz?

package-info.java

Plusy
- Nowszy
Cons
- Nadużycie klasy - Klasy dotyczą kodu, a nie tylko komentarzy

pakiet.html

Plusy
- Rozszerzenie HTML oznacza, że nie jest to kod
- Podświetlanie składni w edytorach IDE / tekstowych
Cons
- Żaden?

Dla mnie zawsze korzystałem z Package.html. Ale zastanawiam się, czy to właściwy wybór.

java javadoc

— TheLQ
źródło

package-info.javamoże zawierać adnotacje [pakiet] - niekoniecznie wszystkie dokumenty API.

— Tom Hawtin - tackline

Nie kwalifikowałbym Package-info.java jako nadużycie klasy. Jest to plik źródłowy Java (ma rozszerzenie „.java”), ale nie jest plikiem klasy, ponieważ nie zawiera deklaracji klasy. W rzeczywistości nie może zawierać deklaracji klasy, ponieważ „informacje o pakiecie” nie są prawidłową nazwą klasy.

— Scrubbie

Innym powodem używania package-info.java zamiast package.html może być to, że .java nie implikuje określonego formatu wyjściowego dokumentacji. Na przykład możesz chcieć wypisać javadoc jako LaTeX lub jako plik PDF. W zależności od implementacji kompilatora javadoc może to powodować problemy w przypadku .html.

— honeyp0t

Właściwie @Scrubbie - chociaż powinieneś mieć rację, myślę, że możesz tam określić klasy prywatne. :-( Zgadzam się jednak z twoim sentymentem, używanie package-info.javaJavadoc i Adnotacji nie jest nadużyciem klasy.

— mjaggard

@JonasN patrz stackoverflow.com/a/14708381/751579 (Wiem, że miałeś ten problem 3 lata temu, ale może ktoś inny potrzebuje teraz napiwku)

— davidbak

269

package-info.java: „Ten plik jest nowy w JDK 5.0 i jest lepszy niż pakiet.html.” - javadoc - Generator dokumentacji Java API

Dodatek: Dużą różnicą wydają się być adnotacje pakietowe . Trochę więcej jest uzasadnienia w deklaracjach pakietów 7.4 .

Dodatek: Funkcja adnotacji jest również wymieniona tutaj i tutaj .

Dodatek: Zobacz także Po co package-info.java? .

— trashgod
źródło

Czy jest jakiś konkretny powód, dla którego jest preferowany?

— TheLQ

@TheLQ: Zgaduję adnotacje pakietu, ponieważ kompilator ma więcej informacji do pracy; więcej powyżej.

— trashgod

Adnotacje do pakietów są dla mnie nowe i wydają się dobrym powodem do utworzenia pliku package-info.java ze względu na jego zakres.

— układarka

Edytuj odpowiedź jeszcze trochę: wyjaśnij „adnotację pakietu” - adnotację, która ma być stosowana do wszystkich klas w pakiecie lub w inny sposób do pakietów jako całości. Link tech.puredanger.com był jedynym, który naprawdę wyjaśnił, dlaczego powinienem się tym przejmować. To powiedziawszy, to dobry, pomocny link.

— Roboprog,

Korzystając z package-info.java, możesz używać {@link} i innych dokumentów. Gdy połączysz klasę java.lang, po wygenerowaniu javadoc automatycznie otrzymasz {@link} wskazujący na javadoc online klasy pasujący do używanego jdk; ide może również pomóc w wykryciu złych linków podczas refaktoryzacji refaktoryzacji.

— Luigi R. Viggiano