Cuando ejecuto CheckStyle sobre mi proyecto Java, dice Missing package-info.java file.para algunas clases, pero no para todas. Realmente no puedo entender por qué este mensaje aparece solo a veces. Además, mi proyecto funciona perfectamente sin el paquete-info.java.

¿Qué hace el package-info.java? ¿Realmente lo necesito para mis proyectos Java?

Se utiliza para generar javadocs para un paquete.

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

Generará información del com.domainpaquete para el paquete:

Resultado de ejemplo: https://docs.oracle.com/javase/7/docs/api/java/awt/package-summary.html

Anotaciones

Otra buena razón para usar package-info.java es agregar anotaciones predeterminadas para que las use FindBugs . Por ejemplo, si pones esto en tu archivo de información del paquete:

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

luego, cuando findbugs se ejecuta en el código de ese paquete, se supone que todos los métodos y campos no son nulos a menos que los anote con @CheckForNull. Esto es mucho más agradable e infalible que requerir que los desarrolladores agreguen @NonNullanotaciones a cada método y campo.

No solo algunas anotaciones de findbugs, sino que muchas anotaciones de Java en bibliotecas comunes tienen el java.lang.annotation.ElementType.PACKAGEtipo como uno de los valores posibles de su propia java.lang.annotation.Targetanotación, por ejemplo:

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

y mucho más.

Este package-info.javaarchivo sería el archivo, donde puede colocar tales anotaciones (junto con el javadoc).

Un archivo package-info.java permite agregar javadoc para documentar un paquete completo. Consulte http://docs.oracle.com/javase/7/docs/api/java/applet/package-summary.html por ejemplo.

Si no le importa que falte la documentación del paquete, ignore la advertencia o desactive la verificación JavadocPackage .

El paquete-info.java es un archivo Java que se puede agregar a cualquier paquete fuente Java. Se utiliza para proporcionar información a nivel de "paquete" según su nombre. Contiene documentación y anotaciones utilizadas en el paquete.

El ejemplo de javadoc ya se proporciona en la respuesta, la parte siguiente explica cómo funciona en caso de anotaciones.

Por ejemplo, en el archivo siguiente se utiliza para "sustituir" la aparición de joda.time.DateTime con 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; 

Hay una serie de anotaciones disponibles con las que se pueden utilizar para realizar diferentes cosas a nivel de "paquete". Se puede encontrar en https://docs.jboss.org/hibernate/orm/3.5/api/org/hibernate/annotations/package-summary.html