Why is package-info.java useful?

Question

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

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.

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).

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.

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