Dlaczego package-info.java jest przydatne?

101

Kiedy uruchamiam CheckStyle na moim projekcie Java, pojawia się komunikat Missing package-info.java file. o niektórych klasach, ale nie o wszystkich. Naprawdę nie mogę zrozumieć, dlaczego ta wiadomość pojawia się tylko czasami. Ponadto mój projekt działa doskonale bez pakietu package-info.java.

Co robi pakiet package-info.java? Czy naprawdę potrzebuję tego do moich projektów Java?

Sokrates
źródło
3
Możesz ich używać do dokumentowania lub dodawania adnotacji na poziomie pakietu. Zobacz to pytanie .
McDowell
Przez cały ten czas byłem fanem package-info.java, ale zastanawiam się, czy README.md jest bardziej odpowiedni w 2018 roku
Sridhar Sarnobat
@ Sridhar-Sarnobat Oprócz package-info.java i README.md z Git, istnieje możliwość dodania w Confluene również biletów Jira. W ten sposób można dodawać również diagramy, przepływy pracy lub filmy.
Sokrates
1
Czy wiesz, że możesz tam również napisać inny kod? Jak klasy itp ... Dziwne!
sproketboy

Odpowiedzi:

109

Służy do generowania javadocs dla pakietu.

/**
* Domain classes used to produce .....
* <p>
* These classes contain the ......
* </p>
*
* @since 1.0
* @author somebody
* @version 1.0
*/
package com.domain;

Wygeneruje informacje o com.domainpakiecie:

Przykładowy wynik: https://docs.oracle.com/javase/7/docs/api/java/awt/package-summary.html

m-szalik
źródło
przepraszam, nadal nie jest jasne, do której części Example resultsię odnosisz, czy to plik readme.md?
shareef
51

Adnotacje

Innym dobrym powodem korzystania z package-info.java jest dodanie domyślnych adnotacji do użytku przez FindBugs . Na przykład, jeśli umieścisz to w swoim pliku z informacjami o pakiecie:

@DefaultAnnotation(NonNull.class)
package com.my.package;

wtedy, gdy findbugs działa na kodzie w tym pakiecie, zakłada się, że wszystkie metody i pola nie mają wartości null, chyba że dodasz do nich adnotację @CheckForNull. Jest to o wiele przyjemniejsze i bardziej niezawodne niż wymaganie od programistów dodawania @NonNulladnotacji do każdej metody i pola.

mdhirsch
źródło
12

Nie tylko niektóre adnotacje findbugs, ale wiele adnotacji Java we wspólnych bibliotekach ma java.lang.annotation.ElementType.PACKAGEtyp jako jedną z możliwych wartości własnej java.lang.annotation.Targetadnotacji, np .:

com.google.gwt.core.client.js.JsNamespace
com.querydsl.core.annotations.Config
com.sun.xml.bind.XmlAccessorFactory
groovy.transform.BaseScript
java.lang.Deprecated
javax.annotation.Generated
javax.xml.bind.annotation.XmlAccessorOrder
org.hibernate.annotations.TypeDef
net.sf.ehcache.pool.sizeof.annotations.IgnoreSizeOf
org.apache.hive.common.HiveVersionAnnotation
org.apache.wicket.authroles.authorization.strategies.role.annotations.AuthorizeAction
org.codehaus.commons.nullanalysis.NotNullByDefault
org.eclipse.persistence.oxm.annotations.XmlNameTransformer
org.glassfish.jersey.Beta
org.jgroups.annotations.Experimental

i wiele więcej.

Ten package-info.javaplik byłby plikiem, w którym można umieścić takie adnotacje (wraz z javadoc).

Rene Mazala
źródło
5

Plik package-info.java plik jest Java, które można dodać do dowolnego pakietu źródłowego Javy. Służy do dostarczania informacji na poziomie „pakietu” zgodnie z jego nazwą. Zawiera dokumentację i adnotacje używane w pakiecie.

przykład javadoc jest już podany w odpowiedzi, poniższa część wyjaśnia, jak to działa w przypadku adnotacji.

Na przykład w poniższym pliku służy do „zastąpienia” wystąpienia joda.time.DateTime wartością org.jadira.usertype.dateandtime.joda.PersistentDateTime

@TypeDefs({
    @TypeDef(name = "PersistentDateTime", typeClass = PersistentDateTime.class, defaultForType=DateTime.class)})

package xyz.abc;

import org.hibernate.annotations.TypeDef;
import org.hibernate.annotations.TypeDefs;
import org.jadira.usertype.dateandtime.joda.PersistentDateTime;
import org.joda.time.DateTime; 

Dostępnych jest wiele adnotacji, za pomocą których można wykonać różne czynności na poziomie „pakietu”. Można go znaleźć pod adresem https://docs.jboss.org/hibernate/orm/3.5/api/org/hibernate/annotations/package-summary.html

subodhkarwa
źródło