Pod::Coverage

El módulo Pod::Coverage analiza un fuente de Perl buscando documentación referente a métodos y funciones.

Concretamente intenta localizar bloques =head (de nivel dos en adelante) y elementos de listas =item que hace referencia a una función.

En el siguiente ejemplo:

    1 package Foo;
    2 
    3 =item foo
    4 
    5 The foo subroutine ...
    6 
    7 =cut
    8 
    9 sub foo { 1; }
   10 
   11 sub bar { 1; }
   12 
   13 1;
   14 __END__

La cobertura sería del 50% (0.5) puesto que únicamente aparece una referencia a la función foo.

Los parámetros en la creación de un objeto Pod::Coverage son interesantes sobre todo si se utilizan mecanismos de herencia:

• package: nombre del paquete a analizar.
• private: lista de expresiones regulares que indican qué símbolos deben ser considerados como privados y para los que no es necesario buscar documentación. La lista es completa e incluye todas las operaciones con objetos Tie.
• also_private: lista de elementos (expresiones regulares) a añadir a la anterior
• trustme: lista como la anterior que determina qué símbolos debe asumir el módulo como correctamente documentados aunque no encuentre nada sobre ellos.
• pod_from: ruta opcional al archivo del cual obtener la documentación; si se omite se utiliza Pod::Find.

En realidad este módulo es verdaderamente útil cuando se utiliza la versión para construir tests, de la que hablaremos a continuación.

Test::Pod::Coverage

El módulo Test::Pod::Coverage proporciona mecanismos para testear la cobertura de la documentación sobre los módulos fuente.

Un ejemplo de uso es:

    1 use Test::Pod::Coverage tests=>1;
    2 pod_coverage_ok( "Foo::Bar", "Foo::Bar is covered" );

Los métodos principales son los siguientes:

podcoverageok( $module, [ $params, ] $msg)

Comprueba la cobertura documental del módulo indicado. Se le puede proporcionar un referencia a un hash con parámetros para Pod::Coverage y, por supuesto, un texto para identificar el test.

Entre los parámetros existe uno especial llamado coverage_class que determina qué clase utilizar para trabajar; el valor predeterminado es, obviamente, Pod::Coverage.

allpodcoverage_ok( [$parms, ] $msg )

Igual que la anterior, pero utilizando todos los módulos de la distribución. Para buscarlos emplea el siguiente método.

all_modules( [@dirs] )

Localiza todos los módulos en la lista de directorios proporcionada incluyendo la búsqueda en subdirectorios.

Si no se le proporciona ningún parámetro emplea, por este orden, los siguientes:

1. blib
2. lib

Los módulos que retorna están en nomenclatura Perl, al estilo de Foo::Bar y no como Foo/Bar.pm.

Herencia y cobertura

Supongamos que tenemos una clase padre que proporciona tres métodos heredables: new, init y dump, los cuales puede o no estar correctamente documentados por lo que escribimos un test como el siguiente:

    1 pod_coverage_ok( "MyPackage" );

en el cual no se permiten excepciones, si la cobertura no es completa el test falla.

Ahora tenemos tres módulos derivados de él que crean sus correspondientes objetos mediante herencia, y que no van a documentar estos métodos porque ni siquiera figuran físicamente en ellos.

Podemos añadir estas líneas al test anterior:

    1 my $trustme = {
    2     trustme => [qr/^(new|init|dump)$/]
    3     };
    4 
    5 pod_coverage_ok( "MyPackage::Type1",    $trustme );
    6 pod_coverage_ok( "MyPackage::Null",     $trustme );
    7 pod_coverage_ok( "MyPackage::Complex",  $trustme );

y nos aseguramos de que los módulos fallen por sí mismos, y no por lo que hereden de otros.

Cobertura automática

Si queremos incluir un test de cobertura de documentación en nuestros módulos, pero que no sean un requisito imprescindible para instalarlos el autor recomienda utilizar el siguiente test:

    1 use Test::More;
    2 eval "use Test::Pod::Coverage";
    3 plan skip_all => "Test::Pod::Coverage required for testing pod coverage" if $@;
    4 
    5 all_pod_coverage_ok();

Que sólo actuará en caso de que exista este módulo presintalado y que, de paso, encontrará todos los módulos de la distribución y efectuará un test sobre ellos.