Why is package-info.java useful?

Question

When I run CheckStyle over my Java project it says Missing package-info.java file. for some classes, but not all of them. I can't really figure out why this message appears only sometimes. Furthermore my project runs perfectly fine without the package-info.java.

What does the package-info.java do? Do I really need it for my Java projects?

You can use them for documenting or annotating at the package level. See [this question](http://stackoverflow.com/questions/3644726/javadoc-package-html-or-package-info-java). — McDowell, Feb 28 '14 at 12:42
I've been a fan of package-info.java all this time but I wonder if a README.md is more suitable in 2018 — Sridhar Sarnobat, Mar 05 '18 at 20:15
@Sridhar-Sarnobat Besides package-info.java and README.md from Git, there is the possibility of Confluene possibly adding Jira tickets as well. That way also diagrams, workflows or videos may be added. — Socrates, Mar 05 '18 at 20:34
Did you know that you can also write other code in there too? Like classes etc... Weird! — sproketboy, Mar 29 '18 at 08:10
Is package-info used only for documentation and package annotation? Does it something like package level import if classes? For eg if we import a class in package-info.java can use that class in other files of the package without explicitly importing the file in the said file? — Gautham Arunachalam, Oct 05 '22 at 08:09

m-szalik · Accepted Answer · 2018-06-15T23:22:12.690

147

It is used to generate javadocs for a package.

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

Will generate package info for com.domain package:

Example result: https://docs.oracle.com/javase/7/docs/api/java/awt/package-summary.html

edited Jun 15 '18 at 23:22

answered Feb 28 '14 at 12:46

m-szalik

3,546
1
21
28

sorry still not clear which part you refere to `Example result` is it the readme.md ? – shareef Jun 11 '18 at 19:49
3

It its actually used for more than generating javadocs. See https://www.baeldung.com/java-package-info#package-annotations. – Gerardo Cauich Aug 16 '22 at 21:26

score 68 · Answer 2 · edited Nov 08 '18 at 19:32

Annotations

Another good reason to use package-info.java is to add default annotations for use by FindBugs. For instance, if you put this in your package-info file:

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

then when findbugs runs on the code in that package, all methods and fields are assumed to be non-null unless you annotate them with @CheckForNull. This is much nicer and more foolproof than requiring developers to add @NonNull annotations to each method and field.

score 15 · Answer 3 · answered Jan 04 '17 at 15:42

Not only some findbugs annotations, but a lot of java annotations in common libraries have the java.lang.annotation.ElementType.PACKAGE type as one of the possible values of their own java.lang.annotation.Target annotation, e.g.:

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

and much more.

This package-info.java file would be the file, where you can place such annotations (along with the javadoc).

score 9 · Answer 4 · edited Oct 07 '17 at 01:44

9

A package-info.java file allows adding javadoc to document a whole package. See http://docs.oracle.com/javase/7/docs/api/java/applet/package-summary.html for example.

If you don't care about missing package documentation, then ignore the warning or disable the JavadocPackage check.

edited Oct 07 '17 at 01:44

Peter Rader

237
3
14

answered Feb 28 '14 at 12:44

JB Nizet

678,734
91
1,224
1,255

Subodh Karwa · Answer 5 · 2019-02-13T10:16:53.603

The package-info.java is a Java file that can be added to any Java source package. It is used to provide info at a "package" level as per its name. It contains documentation and annotations used in the package.

javadoc example is already provided in the answer, the below part explains how it works incase of annotations.

For example, in the below file it is used to "substitute" the occurance of joda.time.DateTime with 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;

There are a number of annotations available with which can be used to perform different things at "package" level. It can be found at https://docs.jboss.org/hibernate/orm/3.5/api/org/hibernate/annotations/package-summary.html

Why is package-info.java useful?

5 Answers5

Annotations