Cobertura Javadoc de clases

Actualizado el 15 de noviembre de 2026

Sigla Jc (Jc(rec) en la variante recursiva de paquete)
Aspecto «Documentación»
Se mide en paquete, módulo, proyecto
Tipo de valor proporción entre 0 y 1, que el plugin muestra como porcentaje
Dirección más alto es mejor
Stau Metro PercentClassesJavadocedPackage, PercentClassesJavadocedRecursivePackage, PercentClassesJavadocedModule, PercentClassesJavadocedProject

En pocas palabras

De todas las clases que hay en un paquete, módulo o proyecto, dice qué parte tiene un comentario Javadoc encima. Un 100 % significa que todas lo tienen; no dice si el comentario es bueno.

Qué mide

La cobertura de documentación a nivel de clase: de cuántas clases se ha escrito, al menos, una descripción formal. Funciona como la cobertura de tests: dice dónde falta, no si lo que hay es de calidad. Un comentario que repite el nombre de la clase cuenta igual que uno excelente.

Cómo se calcula

Jc=clases con comentario /∗∗⋯∗/ en su declaracioˊnclases contadas\text{Jc} = \frac{\text{clases con comentario } /** \dots */ \text{ en su declaración}}{\text{clases contadas}}

Entran en el recuento las clases nombradas de los ficheros Java: clases ordinarias y abstractas, interfaces, enumerados, record, tipos de anotación y clases anidadas. Quedan fuera las clases anónimas, las locales (declaradas dentro de un método) y los parámetros de tipo; una clase con nombre declarada dentro de una anónima o de una local sí cuenta. Una clase está «documentada» si tiene un comentario de documentación; el contenido no se examina.

Un comentario de documentación solo es reconocido como tal cuando precede inmediatamente a la declaración (véase «Líneas de Javadoc»).

Ejemplo

package shop;

/** Catalog of products. */
public class Catalog {
    static class Entry {
    }
}

enum Status { OPEN, CLOSED }

Clases contadas: Catalog, Catalog.Entry y Status. Solo Catalog tiene Javadoc: Jc = 1 / 3 ≈ 33,3 %.

Cómo interpretarla

No hay umbrales de referencia en Stau Metro. Una orientación razonable:

  • En un paquete, módulo o proyecto que ofrece una API a terceros, apunta a un valor alto: las clases son lo primero que busca quien usa la biblioteca.
  • En una aplicación cerrada, un valor bajo es una decisión de equipo y no un defecto en sí. Lo que importa es si la documentación que falta es la que hace falta.
  • Las clases anidadas y los enumerados pequeños cuentan igual que las grandes, y suelen bajar el porcentaje.

Ojo. La cobertura cuenta clases de cualquier visibilidad, no solo las públicas. Un paquete con muchas clases internas sin documentar puede salir mal parado aunque su API pública esté completa.

Relación con otras métricas

En las herramientas

Stau Metro. PercentClassesJavadocedPackage, PercentClassesJavadocedModule y PercentClassesJavadocedProject. La variante recursiva de paquete (PercentClassesJavadocedRecursivePackage) incluye las clases de los subpaquetes. Solo se miran ficheros Java.

  • Un paquete o proyecto solo tiene fila si cuenta alguna clase; un módulo tiene fila por cada fichero Java, de modo que un módulo sin clases cuenta 0 de 0 y no tiene valor.
  • Entran también las clases de los ficheros de test que estén en el ámbito.
  • No existe a nivel de clase o de interfaz: una clase no se cubre a sí misma.