Fix pod errors #1055

Closed
wants to merge 20 commits into
from

Projects

None yet

3 participants

@paultcochrane
Contributor

These changes correct almost all of the pod errors found by podchecker.

The only file I can't update is lib/IO/CaptureOutput.pm since this file contains embedded wikidoc documentation, which is similar to POD and thus causes podchecker to raise errors. Should I convert this documentation to POD? Then the pod_syntax.t test would pass.

Comments as usual welcome.

paultcochrane added some commits Mar 8, 2014
@paultcochrane paultcochrane [lib] using Pod::Checker to check pod
Pod::Simple was missing many warnings and errors and thus has been replaced
by Pod::Checker.  This is sensible, since the advice given by the
`pod_syntax.t` test when errors occur is that one should use `podchecker` to
investigate errors in detail, thus we should be using Pod::Checker
internally to begin with.
58a1174
@paultcochrane paultcochrane [tools] fixing errors in pod found by podchecker 733b86e
@paultcochrane paultcochrane [t] correcting pod errors found by podchecker 643d521
@paultcochrane paultcochrane [string/encoding] Adding missing =back pod statements
This fixes pod errors found by podchecker
f43d2d8
@paultcochrane paultcochrane [pmc] correcting pod errors found by podchecker 3e1cf51
@paultcochrane paultcochrane [runcore] correcting pod errors found by podchecker 81b6ee3
@paultcochrane paultcochrane [platform] correcting pod errors found by podchecker 0a5bfba
@paultcochrane paultcochrane [ops] adding missing =back to pod; found by podchecker e818c3f
@paultcochrane paultcochrane [io] correcting pod error found by podchecker aae12c9
@paultcochrane paultcochrane [interp] adding missing =back in pod found by podchecker 9a65494
@paultcochrane paultcochrane [gc] correcting pod errors found by podchecker df52544
@paultcochrane paultcochrane [dynpmc] adding missing =back in pod found by podchecker a540f6d
@paultcochrane paultcochrane [src] correcting pod errors found by pychecker c207ca0
@paultcochrane paultcochrane [runtime] correcting pod errors found by podchecker bc4edb6
@paultcochrane paultcochrane [lib] correcting pod errors found by podchecker c2e6e75
@paultcochrane paultcochrane [examples] correcting pod errors found by podchecker 65a5e4e
@paultcochrane paultcochrane [docs] Correcting pod errors found by podchecker
Also removing the empty GENERATED FILES section.  It seems that this section
was intended to be written but was not written.
14b1e5e
@paultcochrane paultcochrane [docs] Correcting pod errors found by podchecker
Removed internal links to the "Upcoming Releases" appendix.  A grep of the
sources shows that this no longer exists within the repository.
7a359ad
@paultcochrane paultcochrane [docs] correcting pod errors found by podchecker f12ed57
@paultcochrane paultcochrane [compilers] correcting pod errors found by podchecker f85cf7e
@jkeenan
Contributor
jkeenan commented Mar 9, 2014

On 3/8/14 5:07 PM, Paul Cochrane wrote:

These changes correct almost all of the pod errors found by podchecker.

The only file I can't update is lib/IO/CaptureOutput.pm since this file contains embedded wikidoc documentation, which is similar to POD and thus causes podchecker to raise errors. Should I convert this documentation to POD? Then the pod_syntax.t test would pass.

Yes, I think you can take out the wikidoc formatting.

My guess is that when David Golden took over maintenance of
IO::CaptureOutput, he was going through a phase of wiki fandom. I liked
the module and found it vary useful in testing the Perl parts of the
Parrot codebase, which is why I copied it into Parrot. Until you
brought this up, I never noticed the wikidoc formatting. David
subsequently went on to write and champion Capture::Tiny, so I doubt
he'll mind minor adjustments to IO::CaptureOutput.

Perhaps you could include a note in the POD indicating that we (Parrot)
have taken out the wikidoc formatting but otherwise have made no changes
in the documentation.

Thank you very much.
Jim Keenan

@rurban
Member
rurban commented Mar 9, 2014

I did the same already in the ptc/pod_checker-gh1053 branch. See GH #1053 and my commit af695a1.
I also converted the wikidoc format to pod, but stopped on the man 3 links to system, fork and such.

And I don't really like Pod::Checker as does not help much. It detects some common mistakes (missing =back), but also complains on validly parsed pod (such as requiring an empty line after =cut), and the L<|> issue and on =begin format, =end format.

@paultcochrane
Contributor

However, it does a better job at catching errors than Pod::Simple. Also, if the advice is to use podchecker as the tool to check for problems e.g. podchecker docs/*/*.pod then one gets all of these problems anyway.

@rurban
Member
rurban commented Mar 10, 2014

Merged a rebased and fixed version of ptc/fix_pod_errors-gh1055 with
commit 9a67ff6
Author: Reini Urban rurban@cpanel.net
Date: Mon Mar 10 13:08:34 2014 -0500

@rurban rurban closed this Mar 10, 2014
@paultcochrane paultcochrane deleted the paultcochrane:ptc/fix_pod_errors branch Mar 16, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment