How can I check if a function has POD (perl in-file documentation)?

Question

Is there any library that can tell me if a specific function has POD? I want to add that into our build system.

As in, the convention as established in the docs on POD,

=item stuff()

This function does stuff.

=cut

sub stuff {
  ...
}

I want to write something like this

my @functions = get_functions_with_PPI($file);

foreach my $func (@functions) {
  unless ( file_has_POD_for_func($file,$func) ) {
    say "The function $func is undocumented!";
  }
}

I need something that does file_has_POD_for_func as documented above.

It looks like you are trying to replicate exactly what Pod::Coverage does. And if you want to incorporate it into your test suite, then you can use Test::Pod::Coverage. — Andy Lester, Aug 19 '22 at 21:45

score 4 · Accepted Answer · answered Aug 19 '22 at 21:06

4

`Pod::Coverage`

Pod::Coverage does what you want. Devel::Cover uses it internally.

answered Aug 19 '22 at 21:06

Evan Carroll

78,363
46
261
468

3

In test suites, Test::Pod::Coverage wraps Pod::Coverage. – brian d foy Aug 20 '22 at 03:11

score 2 · Answer 2 · edited Aug 20 '22 at 17:43

Instead of using PPI, use something like Pod::Simple or Pod::Parser to parse the source file.

Note that you will have to rely on the author following conventions of mentioning the functions in an =item or (more commonly) =head2 tag.

You may want to look at the source for something like Pod::Coverage that checks if all functions in a module are mentioned in POD, assuming that isn't something you are trying to do already.

How can I check if a function has POD (perl in-file documentation)?

2 Answers2

Pod::Coverage

`Pod::Coverage`