Luego de consultar expertos en la materia, programadores de diversas ramas y profesores dimos con la respuesta a la interrogande y la plasmamos en este post.
Solución:
Se utiliza para generar javadocs para un paquete.
/**
* Domain classes used to produce .....
*
* These classes contain the ......
*
*
* @since 1.0
* @author somebody
* @version 1.0
*/
package com.domain;
Generará información del paquete para com.domain 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 usen Buscar errores. 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 sonnull a menos que los anote con @CheckForNull. Esto es mucho mejor y más infalible que requerir que los desarrolladores agreguen @NonNull anotaciones a cada método y campo.
No solo algunas anotaciones de findbugs, sino muchas anotaciones de Java en bibliotecas comunes tienen la java.lang.annotation.ElementType.PACKAGE tipo como uno de los posibles valores de su propio java.lang.annotation.Target anotació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.java file sería el archivo, donde puede colocar dichas anotaciones (junto con el javadoc).
Al final de la artículo puedes encontrar las explicaciones de otros gestores de proyectos, tú también tienes el poder insertar el tuyo si te gusta.