/ 
Rakudo-Star-2012.08_000
2 ++
/ Parrot::Test::Pod

NAME

Parrot::Test::Pod - Utilities for tests which test POD

SYNOPSIS

    use Parrot::Test::Pod;

    $self = Parrot::Test::Pod->new( {
        argv => [ @ARGV ],
    } );

DESCRIPTION

This module provides utilities for tests in the Parrot test suite which test the validity of documentation written in the POD format.

METHODS

new()

Purpose: Parrot::Test::Pod constructor.

Arguments: Hash reference holding, at a minimum, one element keyed by argv, whose value is typically a reference to @ARGV.

Return Value: Parrot::Test::Pod object.

identify_files_for_POD_testing()

Purpose: Identifies files in the Parrot distribution which are likely to merit examination for the validity of their POD.

The subroutine itself does a first pass at that process, and takes as one of its arguments a reference to a subroutine which does a second such pass.

Arguments:

    $need_testing_ref = $self->identify_files_for_POD_testing( {
        second_analysis => 'oreilly_summary_malformed',
    } );

Return Value: A reference to a hash where each element's key is the path to a file deemed needing examination for the validity of its POD. The element's value is either 1 or 2, depending on whether it was seen in MANIFEST or MANIFEST.generated or both.

Comment: The first time this subroutine is invoked, it creates a Storable file in the top-level Parrot directory called .pod_examinable.sto. That file holds a hash which serves as a lookup table for files which might need examination for validity of their POD. When the subroutine is subsequently invoked, that file is read so that one scan of the directory structure is eliminated.

oreilly_summary_malformed()

Purpose: An instance of the "second pass" type of subroutine passed to identify_files_for_POD_testing() second_analysis argument.

In this instance, we omit:

  • files in docs/book/ that use extended O'Reilly-specific POD;

  • programs that generate POD; and

  • files which for other testing purposes have deliberately malformed POD.

Arguments: Two scalar arguments:

  • Reference to hash of files meriting analysis, generated in first part of identify_files_for_POD_testing().

  • Path to build directory (currently, the top-level Parrot directory).

Return Value: Reference to hash of files meriting analysis, i.e., the results of the first pass minus the results of the second pass.

AUTHOR

James E Keenan, refactored from earlier code

HISTORY

* [2012-06-05] Updated by Alvis Yardley <ac.yardley@gmail.com>