Padre::Plugin::FormBuilder::Perl, patch to add POD to plugin dialogs

[bowtie]

Added auto POD generation.

lib/Padre/Plugin/FormBuilder/Perl.pm

@@ -23 +23 @@
 use 5.008005;
 use strict;
 use warnings;
-use Scalar::Util   ();
+use Scalar::Util ();
 use FBP::Perl 0.38 ();
-use Mouse     0.61;
+use Mouse 0.61;
 
 our $VERSION = '0.02';
 
@@ -45 +45 @@
     default  => 0,
 );
 
-
-
-
-
 ######################################################################
 # Dialog Generators
 
@@ -59 +55 @@
     my $code    = $self->SUPER::dialog_class($name);
 
     # Customise the package name if requested
-    if ( $package ) {
+    if ($package) {
         splice( @$code, 0, 1, "package $package;" );
     }
 
     # Prepend an auto-generated "Don't Modify" warning
     my $class = Scalar::Util::blessed($self);
     splice(
-        @$code, 1, 0,
+        @$code,
+        1,
+        0,
         "",
         "# This module was generated by $class.",
         "# To change this module, edit the original .fbp file and regenerate.",
@@ -75 +73 @@
 
     # Append the copywrite statement that Debian/etc need
     push @$code, <<'END_PERL';
+=pod
+
+=over 4
+
+=item new ()
+
+Constructor. Auto-generated by Padre::Plugin::FormBuilder.
+
+=back
+
+=head1 AUTHOR
 
-# Copyright 2008-2011 The Padre development team as listed in Padre.pm.
-# LICENSE
-# This program is free software; you can redistribute it and/or
-# modify it under the same terms as Perl 5 itself.
+Adam Kennedy E<lt>adamk@cpan.orgE<gt>
+
+=head1 SEE ALSO
+
+L<Padre>
+
+=head1 LICENSE AND COPYRIGHT
+
+Copyright (c) 2008-2011 The Padre development team as listed in Padre.pm.
+
+This module is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+=cut
+
 END_PERL
 
     return $code;
@@ -91 +111 @@
     my $lines  = $self->SUPER::dialog_new($dialog);
 
     # Find the full list of public windows
-    my @public = grep {
-        $_->permission eq 'public'
-    } $dialog->find( isa => 'FBP::Window' );
+    my @public = grep { $_->permission eq 'public' } $dialog->find( isa => 'FBP::Window' );
 
     if ( $self->encapsulate and @public ) {
+
         # Generate code to save the wxWidgets id values to the hash slots
-        my @save = ( '' );
-        foreach my $window ( @public ) {
+        my @save = ('');
+        foreach my $window (@public) {
             my $name     = $window->name;
             my $variable = $self->object_variable($window);
             push @save, "\t\$self->{$name} = $variable->GetId;";
@@ -116 +135 @@
     my $dialog  = shift;
     my $version = $self->version;
 
-    return [
-        "our \$VERSION = '$version';",
-    ];
+    return [ "our \$VERSION = '$version';", ];
 }
 
 sub dialog_isa {
@@ -126 +143 @@
     my $dialog = shift;
 
     return $self->nested(
-        "our \@ISA     = qw{",
-        "Padre::Wx::Role::Main",
-        "Wx::Dialog",
-        "};",
+        "our \@ISA     = qw{", "Padre::Wx::Role::Main",
+        "Wx::Dialog",          "};",
     );
 }
 
 sub use_wx {
     my $self   = shift;
     my $dialog = shift;
-    return [
-        "use Padre::Wx ();",
-        "use Padre::Wx::Role::Main ();",
-    ];
+    return [ "use Padre::Wx ();", "use Padre::Wx::Role::Main ();", ];
 }
 
 sub window_accessor {
@@ -150 +162 @@
 
     my $object = shift;
     my $name   = $object->name;
-    return $self->nested(
+    my $space  = q{ };
+
+    my @tmp_pod = [
+        "=pod",
+        "$space",
+        "=over 4",
+        "$space",
+        "=item $name ()",
+        "$space",
+        "Public Accessor $name Auto-generated.",
+        "$space",
+        "=back",
+        "$space",
+        "=cut",
+    ];
+
+    my @tmp_accessor_method = $self->nested(
         "sub $name {",
-        "Wx::Window::FindWindowById(\$_[0]->{$name});",
-        "}",
+        "Wx::Window::FindWindowById(\$_[0]->{$name});", "}",
     );
+
+    my @conjoined = ( @tmp_pod, @tmp_accessor_method );
+    return @conjoined;
 }
 
 sub window_event {
@@ -163 +193 @@
     my $event  = shift;
     my $name   = $window->name;
     my $method = $window->$event();
+    my $space  = q{ };
 
-    return $self->nested(
+    my @tmp_pod = [
+        "=pod",
+        "$space",
+        "=over 4",
+        "$space",
+        "=item $method ()",
+        "$space",
+        "Event Handler for $name.$event (Required). Auto-generated.",
+        "You must implement this Method in your calling class.",
+        "$space",
+        "=back",
+        "$space",
+        "=cut",
+    ];
+
+    my @tmp_required_method = $self->nested(
         "sub $method {",
         "\$_[0]->main->error('Handler method $method for event $name.$event not implemented');",
         "}",
     );
+
+    my @conjoined = ( @tmp_pod, @tmp_required_method );
+    return @conjoined;
 }
 
 # Because we expect everything to be shimmed, apply a stricter interpretation

[adamk]

While I like the idea in principle, the quality of the documentation is nearly useless. It should provide much more information.

Rejecting this patch, although I do like the idea.