Чем полезен package-info.java?

Question 1

Когда я запускаю CheckStyle в своем Java-проекте, он говорит Missing package-info.java file.о некоторых классах, но не обо всех. Я не могу понять, почему это сообщение появляется только иногда. Кроме того, мой проект отлично работает без package-info.java.

Что делает package-info.java? Действительно ли он мне нужен для моих Java-проектов?

Question 2

Он используется для создания документации javadoc для пакета.

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

Сгенерирует информацию о com.domainпакете для пакета:

Пример результата: https://docs.oracle.com/javase/7/docs/api/java/awt/package-summary.html

Question 3

Аннотации

Еще одна веская причина использовать package-info.java - добавить аннотации по умолчанию для использования FindBugs . Например, если вы поместите это в свой файл информации о пакете:

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

затем, когда findbugs запускается в коде в этом пакете, все методы и поля считаются ненулевыми, если вы не аннотируете их с помощью @CheckForNull . Это намного приятнее и надежнее, чем требовать от разработчиков добавления @NonNullаннотаций к каждому методу и полю.

Question 4

Не только некоторые аннотации findbugs, но и многие java-аннотации в общих библиотеках имеют java.lang.annotation.ElementType.PACKAGEтип как одно из возможных значений их собственной java.lang.annotation.Targetаннотации, например:

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

и многое другое.

Этот package-info.javaфайл будет файлом, в котором вы можете разместить такие аннотации (вместе с javadoc).

Question 5

Файл package-info.java позволяет добавить javadoc для документирования всего пакета. См., Например, http://docs.oracle.com/javase/7/docs/api/java/applet/package-summary.html .

Если вас не волнует отсутствующая документация по пакету, проигнорируйте предупреждение или отключите проверку JavadocPackage .

Question 6

Package-info.java является Java - файл , который может быть добавлен к любому пакету источника Java. Он используется для предоставления информации на уровне «пакета» в соответствии с его названием. Он содержит документацию и аннотации, используемые в пакете.

Пример javadoc уже приведен в ответе, ниже объясняется, как он работает в случае аннотаций.

Например, в приведенном ниже файле он используется для «замены» появления joda.time.DateTime на 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;

Доступен ряд аннотаций, с помощью которых можно выполнять различные действия на уровне «пакета». Его можно найти на странице https://docs.jboss.org/hibernate/orm/3.5/api/org/hibernate/annotations/package-summary.html.