Raku: POD6 is a PITA

Jeff

• 3 min read
Raku: POD6 is a PITA
Eddie contemplates daffodils, and the cheek of squirrels. Spring 2022, Sussex.

So there's a beast called POD6 lurking in the shadows in Rakuland. It's an ancient monster, that grew out of the depths of Perl - and even then, its forebears predated the era of readable documentation...

My contentious belief is that POD6 is simply not worth the effort. I've tried - sincerely and repeatedly - but it's very hard to love. Maybe you can change my mind?

I want technical code documentation that is:

  • Easy to read at 2:00 am in the server room when I am rostered on support and there is no 3 (let alone 4 or 5) G signal.
  • Easy to read when I'm handed a sheaf of paper, just before coffee, in 6pt Fixedsys wrapped at 80, and the CTO says 'Oh - by the way...'
  • Easy to update when the inevitable happens, and the code makes it's unwilling debut in the Cloud.
  • Complete and Easy to interactively explore when I am the newbie and the 20 year old codebase is >1,000,000 lines.

The only people in the world who like the look of raw POD are died-in-the-wool Perlheads - usually my kind of people, but sadly rarer these days. (Treasure them!). Even my ancient editor sighs, and refuses to colour-me-comment.

So what do I want, do I really really want in a spiced up POD6 alternate reality? I think I can distil it down to two basic things:

  1. Easy to write, read and tart-up documentation in my code - and why reinvent the wheel. I want to read/write/parse standard markdown that is also recognised by my Word Perfect Program Editor as a comment (line or block).
  2. Code exploration documentation that is pretty, interactive, complete (no missing or hidden privates please) and mostly - explorable - I want to conquer that 1,000,000 line Everest codebase. Yeah - you got me, I'm thinking JavaDoc style generated interactive HTML direct from the code-horse's mouth.

So how would this look in an alternate Raku world? Maybe:

Semantic Documentation

=doc README.md

# Jaguart::App::Installer

Jaguart installer - parallell installation of multiple modules on multiple hosts, with pre and post goodness including daemon stop/start/restart.

## Synopsis

  use Jaguart::App::Installer;
  
  my $installer = Jaguart::App::Installer.new;
  
  $installer.stage( 
      :module(< jaguart-etc jaguart-bin >) 
      :host(< quee snik >)
    );
  
  $installer.release;

## Description

The installer relies on lexicons for both host and module information.
See [Jaguart::Config::Module](Jaguart-Config-Module) and [Jaguart::Config::Host](Jaguart-Config-Host)

## Installation

  zef install Jaguart::App::Installer
  
=end README.md

#! The main beastie.
unit class Jaguart::App::Installer;

...

The intent being that content between =doc README.md ... =end README.md is collated into a markdown entity that may/may not be created on disk. Multiple sections with the same name, in the same folder, across multiple source files would be collated into the same README.md for that folder.

More importantly though, the semantic structure - e.g. the ##Description, ##Synopsis sections etc. should be clearly re-specified rather than relying on historic Perl precedence. Raku.land has moved on from cpan... or has it?

Structural Documentation

So how about the interactive codebase exploration - again, the venerable JavaDoc has done most of the analysis, design and many years of usage-testing for this.

I would tweak the JavaDoc Comment standard to be more Rakuish, and ditch the special formatting and embedded HTML in favour of markdown for consistency with semantic documentation.

#! **SuperHero** is the main entity we'll be using to save the world.
#! 
#! Please see the [MugglePerson](lib/MugglePerson) class for true identity
#!
#!  @author Captain America
#!
unit class SuperHero extends Person;

#! The public branding of this hero, e.g Spiderman
has $!hero-name is required;

#! See if an attack will be successful. [Damage System](docs/damage.md).
#!
#! Note - health can go UP as well as down - some heros have insane powers.
#!
#!  @param    $damage    Incoming damage 0-100 == none to unstoppable
#!  @return   The health hero has remaining after attack
#!  @see      [Health and Damage Overview](docs/health.md)
#!  @since    0.1.0
method attack-hero Int (Int:D $damage ) {
  ...
  return $health-remaining;
}

Is that the Full Story?

Nope - clearly not. There are use-cases to explore in Raku's use of $=pod, and there are things that https://docs.raku.org/language/pod talks about that are not (yet?) present in standard markdown.

I see that smart people are looking to use the pre/post declarators to contain SQL fed into a query method - so ok, yes, that is a wow! and maybe that conflicts with semantic standards in the pre-declaratives.

There are also quite a few flavours of markup/down - and each will have it's ardent code warriors.

So in the meantime, I'm going to work on my own markdown - but first, sleep (it's 3:00am in France, on holiday).