Matt S Trout > Rakudo-Star-2012.08_001 > Parrot::Test::Pod

Download:
Rakudo-Star-2012.08_001.tar.gz

Dependencies

Annotate this POD

Source  

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:

Arguments: Two scalar arguments:

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>

syntax highlighting: