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

97

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

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

java maven checkstyle Сократ
источник
3
Вы можете использовать их для документирования или аннотирования на уровне пакета. См. Этот вопрос .
McDowell
Я был поклонником package-info.java все это время, но мне интересно, подходит ли README.md в 2018 году
Шридхар Сарнобат
@ Sridhar-Sarnobat Помимо package-info.java и README.md из Git, Confluene также может добавить билеты Jira. Таким образом также могут быть добавлены диаграммы, рабочие процессы или видео.
Socrates
1
Знаете ли вы, что вы также можете написать там другой код? Как классы и т.д ... Странно!
sproketboy

Ответы:

106

Он используется для создания документации 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

м-салик
источник
извините, все еще не ясно, на какую часть вы ссылаетесь, Example resultэто файл readme.md?
Shareef
50

Аннотации

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

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

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

mdhirsch
источник
12

Не только некоторые аннотации 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).

Рене Мазала
источник
4

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.

Субодкарва
источник