184037 - Run podchecker on .pm files

Status: RESOLVED FIXED

(Bugzilla :: Testing Suite, enhancement)

Description

[Bradley Baetz (:bbaetz)]

Now that we have perldocs, we should check that the POD is valid.

Comment 1

[Frédéric Buclin]

I agree. Maybe should this be a test for runtests.pl.

Comment 2

[Frédéric Buclin]

Attachment: 011podchecker.t, v1

implement POD docs syntax validation.

Comment 3

[Marc Schumann [:Wurblzap]]

Comment on attachment 190375 [details] [diff] [review]
011podchecker.t, v1

>+# Contributor(s): Fr�d�ric Buclin <[e-mail]>

Please convert non-ASCII characters to UTF-8.
It's not a template, but we should set a good example in other files, too.

>+    $file =~ s/\s.*$//; # nuke everything after the first space (#comment)
>+    next if (!$file); # skip null entries

I've seen these two lines in other .t files, too, so it probably does make some
sense. Can you tell me what it's good for?

>+    } elsif (!$good_pod) {
>+        ok(1,"$file has correct POD docs syntax");

This reads weird -- "if not good, then file is correct"... Perhaps the variable
should be named $error_count or something, and checked against zero.

Comment 4

[Frédéric Buclin]

Attachment: 011podchecker.t, v2

My name converted to UTF-8 and $good_pod replaced by $error_count.

About the two lines you mentioned, I have no idea! :)

Comment 5

[Marc Schumann [:Wurblzap]]

Comment on attachment 190381 [details] [diff] [review]
011podchecker.t, v2

The code is good now.

The file should be named 010podchecker.t (or even better 010pod.t -- we may
want to add some other POD tests some time).

In order to go in, the patch needs to include POD error fixes.

>+        ok(1,"$file does not contain any POD docs");
>+        ok(1,"$file has correct POD docs syntax");
>+        ok(0,"$file has incorrect POD docs syntax --ERROR");

Nit: perlpod tells me POD means Plain Old Documentation, so "POD docs" seems
redundant to me, "POD" should do it.

Comment 6

[Marc Schumann [:Wurblzap]]

(In reply to comment #4)
> About the two lines you mentioned, I have no idea! :)

So that's probably another bug, then.

Comment 7

[Marc Schumann [:Wurblzap]]

As discussed on IRC, the patch can get r+ without the POD fixes. Setting
dependency on bug 301967 -- approval (or at least checkin) should wait for bug
301967.

Comment 8

[Frédéric Buclin]

Attachment: 011pod.t, v3

file renamed as pod.t and superfluous "docs" word removed.

Comment 9

[Marc Schumann [:Wurblzap]]

Comment on attachment 190383 [details] [diff] [review]
011pod.t, v3

Good thing to have.

As discussed on IRC, numbering stays at 11 to leave room for the test bug
247560 plans to introduce.

Comment 10

[Frédéric Buclin]

RCS file: /cvsroot/mozilla/webtools/bugzilla/t/011pod.t,v
done
Checking in t/011pod.t;
/cvsroot/mozilla/webtools/bugzilla/t/011pod.t,v  <--  011pod.t
initial revision: 1.1
done

Comment 11

[Marc Schumann [:Wurblzap]]

Bug 301967 is going to land on the trunk, so I think it makes sense to land this
one there as well.

Comment 12

[Myk Melez [:myk] [@mykmelez]]

This seems like a feature we can live without on the branch, simplifying our
testing efforts, no?

Comment 13

[Frédéric Buclin]

2.20rc1:

Checking in t/011pod.t;
/cvsroot/mozilla/webtools/bugzilla/t/011pod.t,v  <--  011pod.t
new revision: 1.1.2.2; previous revision: 1.1.2.1
done