novedades - ¿Cómo maneja Javadoc la visibilidad de los módulos en Java 9?

modulos en java

Question

La herramienta Javadoc genera documentación basada en el modificador de accesibilidad. Por defecto, documenta todas public clases, campos y métodos public y protected . Esto se puede cambiar con las siguientes options :

-público
Muestra solo clases públicas y miembros.

-protegido
Muestra solo clases y miembros protegidos y públicos. Este es el valor predeterminado.

-paquete
Muestra solo paquete, protegido, público y clases y miembros.

-privado
Muestra todas las clases y miembros.

Java 9 introduce el concepto de módulos, y el proyecto Jigsaw lo aplica al JDK existente. Una talk de Mark Reinhold (3º en una serie de charlas sobre módulos) muestra cómo el modificador public ahora tiene diferentes niveles de accesibilidad, dependiendo de la visibilidad del módulo (a través de las exports ):

• público para todos
• públicos pero solo a módulos específicos
• público solo dentro de un módulo

Como ahora no todos los miembros públicos son accesibles, tendría menos sentido continuar con el mismo esquema de generación Javadoc. Solo deben documentarse los miembros que están expuestos con un nivel "suficiente".

¿El módulo Javadoc es consciente? ¿Existen opciones de comando además de las anteriores para manejar la capa de exposición adicional? Para los miembros públicos que están expuestos solo a módulos específicos, el Javadoc los lista, como en

public <module1, module2> static void getDefaultThing()

?

Answer 1

javadoc tiene nuevas opciones que le permiten seleccionar qué elementos están documentados en el módulo, paquete, tipo y nivel de miembro. Usando una versión EA de JDK 9, busque nuevas --module , --show-* y --expand-requires .

Las opciones existentes -public , -protected , -package , -private se han redefinido en términos de las nuevas opciones --show-* , aunque su ayuda en la línea de comandos aún debe actualizarse.

La tabla de conversión práctica-dandy es:

-public
--show-module-contents api --show-packages exported --show-types public --show-members public
-protected (the long-standing default)
--show-module-contents api --show-packages exported --show-types protected --show-members protected
-package
--show-module-contents all --show-packages all --show-types package --show-members package
-private
--show-module-contents all --show-packages all --show-types private --show-members private 

En general, continúe utilizando el valor predeterminado para generar documentación para los usuarios de una API, y tal vez use -package o -private para generar documentación para los desarrolladores de una API. Para un control más preciso, use las opciones subyacentes --show-* .