Feature Proposals » Make TWiki inline documentation conforming to POD spec

Motivation

It is quite fine to use TML for inline documentation: It is "richer" than POD, and people in the TWikiverse are familiar enough with the syntax. However, the current practise is not conforming to the POD specs.

Description and Documentation

The inline docs usually are embedded like this:

=begin twiki

---++ Some TWiki markup

=cut

However, according to the POD spec, begin sections nest and need to be properly ended with an end command, like this:

=begin twiki

---++ Some TWiki markup

=end twiki

=cut

In some modules, for example in TWiki.pm itself, there's a mixture of =pod and =begin twiki invocations, silently assuming that all POD is for TWiki.

Examples

Impact

A "correct" formatting of inline documentation would allow Perl's POD libraries to operate on TWiki modules instead of a homegrown parser. podchecker and podlint could be used in a toolchain without giving hundreds of false positives.

Implementation

Tedious, but straightforward.

The tool tools/gendocs.pl would need to be adjusted accordingly. Very easy if just the syntactical change is taken into account.

There are two ways to avoid the extra two lines for each chunk of documentation. First, a =cut does not end the environment. It is perfectly valid to write:

=begin twiki

---+ First TWiki markup block (module header)

=cut

$some = perl('code');

=pod

---++ Method description

We're still in "begin twiki" mode here!
=cut

# repeat ad libitum

Second, just silently assume that all pod blocks are for TWiki (as some modules, e.g. TWiki::Render, alredy do. Ouch, there's exactly one begin twiki in this module, too):

=pod

---+ First TWiki markup block (module header)

=cut

$some = perl('code');

=pod

---++ Method description

Ok, we're cheating, since all the pod tools will interpret this as
POD.  This may cause warning if we use syntax not valid for POD.
=cut

# repeat ad libitum

As you see, all the difference is just in the first line.

As a side note, gendocs.pl could profit from some overhaul. It makes a few assumptions no longer valid, e.g. subclassing nowadays is done with use parent or use base instead of @ISA, and its documentation is lacking.

-- Contributors: Harald Jörg - 2015-03-21

Discussion