/ 
Test-CPAN-Health-0.1.0
/ Test::CPAN::Health::Check::DocQuality

NAME

Test::CPAN::Health::Check::DocQuality - Check POD syntax and required section presence

SYNOPSIS

use Test::CPAN::Health::Check::DocQuality;

my $check  = Test::CPAN::Health::Check::DocQuality->new;
my $result = $check->run($dist);

printf "%s: %s\n", $result->status, $result->summary;

DESCRIPTION

For each .pm file under lib/, this check:

  1. Runs Pod::Checker to detect POD syntax errors.

  2. Scans for the presence of required =head1 sections: NAME, SYNOPSIS, DESCRIPTION, AUTHOR, and a LICENSE/COPYRIGHT section (under any of the common spellings).

Per-file score: 100 (no errors, all sections), 70 (no errors, some sections missing), 30 (POD errors present), 0 (no POD). The check score is the integer average across all files.

LIMITATIONS

  • Only =head1 headings are matched for required sections.

  • Pod::Checker errors/warnings are counted but not included verbatim in the result details to keep output concise.

run

PURPOSE

Aggregate Pod::Checker results and required-section presence across all .pm files and return a single scored Result.

API SPECIFICATION

INPUT

dist     Test::CPAN::Health::Distribution  required
context  Hashref                           optional

OUTPUT

Test::CPAN::Health::Result with check_id 'doc_quality'.

MESSAGES

Code  | Severity | Message                                          | Resolution
------+----------+--------------------------------------------------+-----------
DQ001 | SKIP     | No .pm files found                               | Add lib/ modules
DQ002 | PASS     | All files have valid POD with required sections  |
DQ003 | WARN     | Some files have POD issues                       | Fix listed files
DQ004 | FAIL     | Most files have POD issues                       | Fix listed files

FORMAL SPECIFICATION

-- Z schema (placeholder) --
DocQualityOp
files         : seq FileName
file_scores   : seq (0..100)
avg_score     : 0..100
-------------------------------------------------------
#files = 0          => status = skip
avg_score >= 90     => status = pass
avg_score >= 50     => status = warn
avg_score < 50      => status = fail

SIDE EFFECTS

Reads source files; invokes Pod::Checker which performs in-process parsing.

USAGE EXAMPLE

my $result = Test::CPAN::Health::Check::DocQuality->new->run($dist);
print $result->summary;

AUTHOR

Nigel Horne, <njh at nigelhorne.com>

LICENSE AND COPYRIGHT

Copyright (C) 2025-2026 Nigel Horne.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.