301967 - Some .pm files have invalid POD syntax

Status: RESOLVED FIXED

(Bugzilla :: Bugzilla-General, defect)

Description

[Frédéric Buclin]

Running podchecker on our .pm files gives some errors. This check should be done
by runtests.pl, see bug 184037.

The purpose of this bug is not to implement this test, but to fix actual broken
files.

Bugzilla.pm pod syntax OK.
Attachment.pm does not contain any pod commands.
*** ERROR: =item without previous =over at line 272 in file Auth.pm
*** WARNING: multiple occurrence of link target 'METHODS' at line - in file Auth.pm
Auth.pm has 1 pod syntax error.
BugMail.pm does not contain any pod commands.
Bug.pm does not contain any pod commands.
CGI.pm pod syntax OK.
Chart.pm does not contain any pod commands.
Classification.pm pod syntax OK.
Component.pm pod syntax OK.
Config.pm pod syntax OK.
Constants.pm does not contain any pod commands.
*** ERROR: Spurious text after =cut at line 866 in file DB.pm
*** ERROR: =over on line 769 without closing =back (at head1) at line 897 in
file DB.pm
*** WARNING: line containing nothing but whitespace in paragraph at line 915 in
file DB.pm
*** ERROR: =over on line 956 without closing =back (at head1) at line 985 in
file DB.pm
*** ERROR: =over on line 1050 without closing =back (at head1) at line 1221 in
file DB.pm
*** ERROR: =over on line 1227 without closing =back (at head2) at line 1229 in
file DB.pm
*** ERROR: =over on line 1233 without closing =back (at head2) at line 1248 in
file DB.pm
*** ERROR: =over on line 1392 without closing =back (at head2) at line 1401 in
file DB.pm
*** ERROR: =over on line 1406 without closing =back (at head1) at line 1428 in
file DB.pm
DB.pm has 8 pod syntax errors.
*** WARNING: line containing nothing but whitespace in paragraph at line 157 in
file Error.pm
Error.pm pod syntax OK.
*** WARNING: Verbatim paragraph in NAME section at line 60 in file Field.pm
Field.pm pod syntax OK.
*** ERROR: =item without previous =over at line 107 in file Flag.pm
*** ERROR: unterminated C<...> at line 725 in file Flag.pm
*** ERROR: =over on line 131 without closing =back (at head1) at line 970 in
file Flag.pm
Flag.pm has 3 pod syntax errors.
FlagType.pm pod syntax OK.
Group.pm pod syntax OK.
Milestone.pm pod syntax OK.
Product.pm pod syntax OK.
Search.pm does not contain any pod commands.
Series.pm does not contain any pod commands.
Template.pm pod syntax OK.
Token.pm does not contain any pod commands.
*** ERROR: =item without previous =over at line 1258 in file User.pm
*** ERROR: Unknown command 'over4' at line 1530 in file User.pm
*** ERROR: =item without previous =over at line 1535 in file User.pm
User.pm has 3 pod syntax errors.
*** WARNING: line containing nothing but whitespace in paragraph at line 403 in
file Util.pm
*** ERROR: =item without previous =over at line 596 in file Util.pm
*** ERROR: =over on line 606 without closing =back (at head2) at line 625 in
file Util.pm
Util.pm has 2 pod syntax errors.
Version.pm pod syntax OK.

Comment 1

[Frédéric Buclin]

Attachment: patch, v1

fix POD syntax.

Comment 2

[Marc Schumann [:Wurblzap]]

Comment on attachment 190400 [details] [diff] [review]
patch, v1

r=wurblzap by runtests.pl and ruling out code modifications.

There are some unnecessary whitespace-only changes in there (removing
whitespace at the end of lines), but I think it's a good opportunity to let
them go in because there are lots of necessary whitespace-only changes POD
requires us to do :)

Moving "1;" in FlagType.pm isn't really part of this bug, but I don't really
mind, either.

>Index: Bugzilla/DB/Mysql.pm
>@@ -653,10 +655,3 @@
>     return $schema;
> }
> 1;
>-
>-__END__

I don't know whether this is a nit or not: you've removed __END__. It seems to
work for me, but I wonder why it was there in the first place. If this change
was intentional and for a reason, please ask for approval or a second review.
If it was by accident, please attach an updated patch and move forward r+.

Comment 3

[Frédéric Buclin]

(In reply to comment #2)
> There are some unnecessary whitespace-only changes in there (removing
> whitespace at the end of lines), but I think it's a good opportunity to let
> them go in because there are lots of necessary whitespace-only changes POD
> requires us to do :)

These are not unnecessary changes. Trailing whitespaces *must* be removed. Else
you get such error messages:

*** WARNING: line containing nothing but whitespace in paragraph at line 921 in
file Bugzilla/DB.pm

*** WARNING: Verbatim paragraph in NAME section at line 60 in file Bugzilla/Field.pm



> >Index: Bugzilla/DB/Mysql.pm
> > 1;
> >-
> >-__END__
> 
> I don't know whether this is a nit or not: you've removed __END__. It seems to
> work for me, but I wonder why it was there in the first place.

It's a way to indicate to Perl that there is no more Perl code after that line.
This is very useful when there is a full POD following the end of the code (we
avoid to waste time scanning the whole file), but in this case this indication
is useless as we are at the end of the file anyway. So yes, removing it was
intentional. :)

Comment 4

[Dave Miller [:justdave]]

does this need to be done on the 2.20 branch as well?  Since the docs tend to
get maintained we might as well if it needs to be.

Comment 5

[Frédéric Buclin]

Attachment: 2.20 backport, v1

The Field.pm file doesn't exist in 2.20, as well as the i_am_cgi() function in
Util.pm. I removed these two sections from the patch for the tip and it applies
cleanly. Running runtests.pl with 011pod.t included shows that this correctly
fixes the POD syntax.

So it shouldn't be too hard to review this backport. ;)

Comment 6

[Frédéric Buclin]

I'm going to check in the patch for the tip now, in order to prevent Tinderbox
to complain when it runs 011pod.t.

I let this bug open till I check in the backport for 2.20.

Comment 7

[Frédéric Buclin]

tip only:

Checking in Bugzilla/Auth.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/Auth.pm,v  <--  Auth.pm
new revision: 1.12; previous revision: 1.11
done
Checking in Bugzilla/DB.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/DB.pm,v  <--  DB.pm
new revision: 1.58; previous revision: 1.57
done
Checking in Bugzilla/Error.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/Error.pm,v  <--  Error.pm
new revision: 1.14; previous revision: 1.13
done
Checking in Bugzilla/Field.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/Field.pm,v  <--  Field.pm
new revision: 1.2; previous revision: 1.1
done
Checking in Bugzilla/Flag.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/Flag.pm,v  <--  Flag.pm
new revision: 1.46; previous revision: 1.45
done
Checking in Bugzilla/FlagType.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/FlagType.pm,v  <--  FlagType.pm
new revision: 1.20; previous revision: 1.19
done
Checking in Bugzilla/User.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/User.pm,v  <--  User.pm
new revision: 1.67; previous revision: 1.66
done
Checking in Bugzilla/Util.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/Util.pm,v  <--  Util.pm
new revision: 1.33; previous revision: 1.32
done
Checking in Bugzilla/Auth/Login/WWW.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/Auth/Login/WWW.pm,v  <--  WWW.pm
new revision: 1.7; previous revision: 1.6
done
Checking in Bugzilla/DB/Mysql.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/DB/Mysql.pm,v  <--  Mysql.pm
new revision: 1.27; previous revision: 1.26
done
Checking in Bugzilla/DB/Schema.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/DB/Schema.pm,v  <--  Schema.pm
new revision: 1.34; previous revision: 1.33
done
Checking in Bugzilla/User/Setting.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/User/Setting.pm,v  <--  Setting.pm
new revision: 1.6; previous revision: 1.5
done

Comment 8

[Marc Schumann [:Wurblzap]]

Comment on attachment 190550 [details] [diff] [review]
2.20 backport, v1

r=wurblzap by runtests.pl and ruling out code modifications.

Comment 9

[Frédéric Buclin]

2.20rc1:

Checking in Bugzilla/Auth.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/Auth.pm,v  <--  Auth.pm
new revision: 1.10.2.2; previous revision: 1.10.2.1
done
Checking in Bugzilla/DB.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/DB.pm,v  <--  DB.pm
new revision: 1.56.2.1; previous revision: 1.56
done
Checking in Bugzilla/Error.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/Error.pm,v  <--  Error.pm
new revision: 1.13.4.1; previous revision: 1.13
done
Checking in Bugzilla/Flag.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/Flag.pm,v  <--  Flag.pm
new revision: 1.45.2.1; previous revision: 1.45
done
Checking in Bugzilla/FlagType.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/FlagType.pm,v  <--  FlagType.pm
new revision: 1.19.2.1; previous revision: 1.19
done
Checking in Bugzilla/User.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/User.pm,v  <--  User.pm
new revision: 1.61.2.4; previous revision: 1.61.2.3
done
Checking in Bugzilla/Util.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/Util.pm,v  <--  Util.pm
new revision: 1.28.2.2; previous revision: 1.28.2.1
done
Checking in Bugzilla/Auth/Login/WWW.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/Auth/Login/WWW.pm,v  <--  WWW.pm
new revision: 1.6.4.1; previous revision: 1.6
done
Checking in Bugzilla/DB/Mysql.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/DB/Mysql.pm,v  <--  Mysql.pm
new revision: 1.24.2.1; previous revision: 1.24
done
Checking in Bugzilla/DB/Schema.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/DB/Schema.pm,v  <--  Schema.pm
new revision: 1.32.2.2; previous revision: 1.32.2.1
done
Checking in Bugzilla/User/Setting.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/User/Setting.pm,v  <--  Setting.pm
new revision: 1.4.2.2; previous revision: 1.4.2.1
done