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
46
package-info.javamoże zawierać adnotacje [pakiet] - niekoniecznie wszystkie dokumenty API.
Tom Hawtin - tackline
52
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
19
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
3
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
2
@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

Odpowiedzi:

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
3
Czy jest jakiś konkretny powód, dla którego jest preferowany?
TheLQ
2
@TheLQ: Zgaduję adnotacje pakietu, ponieważ kompilator ma więcej informacji do pracy; więcej powyżej.
trashgod
3
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
6
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,
5
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