update docs; prefer MooX::PDL2; advice on overloading initialize()

Makefile.PL

@@ -19,8 +19,7 @@ my %WriteMakefileArgs = (
   "PREREQ_PM" => {
     "Moo" => 0,
     "PDL" => "2.000",
-    "PDL::Core" => 0,
-    "parent" => 0,
+    "PDL::Lite" => 0,
     "strict" => 0,
     "warnings" => 0
   },
@@ -33,10 +32,11 @@ my %WriteMakefileArgs = (
     "IPC::Open3" => 0,
     "Moo" => 0,
     "Object::Tiny" => 0,
-    "PDL::Lite" => 0,
+    "PDL" => "2.000",
     "Test::Deep" => 0,
     "Test::More" => 0,
-    "blib" => "1.01"
+    "blib" => "1.01",
+    "parent" => 0
   },
   "VERSION" => "0.02",
   "test" => {
@@ -55,7 +55,6 @@ my %FallbackPrereqs = (
   "Moo" => 0,
   "Object::Tiny" => 0,
   "PDL" => "2.000",
-  "PDL::Core" => 0,
   "PDL::Lite" => 0,
   "Test::Deep" => 0,
   "Test::More" => 0,

README.mkdn

@@ -6,12 +6,68 @@ PDLx::DetachedObject - parent class for subclassing PDL 2.X from class framework
 
 version 0.02
 
+# SYNOPSIS
+
+### Moo
+
+    # DEPRECATED; use MooX::PDL2 instead
+    package MyPDL;
+
+    use Moo;
+    use PDL::Lite;
+
+    extends 'PDLx::DetachedObject';
+
+    has PDL => ( is => 'rw' );
+
+### Class::Tiny
+
+    package MyPDL;
+
+    use Class::Tiny qw[ PDL ];
+
+    use parent 'PDLx::DetachedObject';
+
+### Object::Tiny
+
+    package MyPDL;
+
+    use Object::Tiny qw[ PDL ];
+
+    use parent 'PDLx::DetachedObject';
+
+### Class::Accessor
+
+    package MyPDL;
+
+    use parent 'Class::Accessor', 'PDLx::DetachedObject';
+    __PACKAGE__->follow_best_practice;
+    __PACKAGE__->mk_accessors( 'PDL' );
+
+or with Antlers:
+
+    package MyPDL;
+    use Class::Accessor "antlers";
+    use parent 'PDLx::DetachedObject';
+
+    has PDL => ( is => 'ro' );
+
 # DESCRIPTION
 
-[PDL](https://metacpan.org/pod/PDL) has a [non-standard way of handling
-subclasses](https://metacpan.org/pod/PDL::Objects). Because a **PDL** object is a blessed scalar,
-outside of using inside-out classes as the subclass, there is no easy
-means of adding extra attributes to the object.
+**PDLx::DetachedObject** provides a minimal shim between [PDL](https://metacpan.org/pod/PDL) and
+object-orientation frameworks.  Directly subclassing **PDL** is tricky,
+as a **PDL** object (a piddle) is a blessed scalar, not a blessed hash.
+**PDL** provides an [alternate](https://metacpan.org/pod/PDL::Objects) means of subclassing; this
+class encapsulates that prescription.
+
+For [Moo](https://metacpan.org/pod/Moo) based classes, see [MooX::PDL2](https://metacpan.org/pod/MooX::PDL2), which provides a more
+integrated approach.
+
+## Background
+
+Because a **PDL** object is a blessed scalar, outside of using
+inside-out classes as the subclass, there is no easy means of adding
+extra attributes to the object.
 
 To work around this, **PDL** will treat any hash blessed into a
 subclass of PDL which has an entry with key `PDL` whose value is a
@@ -77,6 +133,14 @@ an **initialize** class method.  The constructor ensures returns a
 properly subclassed hash with the `PDL` key, keeping **PDL** happy.
 When **PDL** calls the **initialize** function it gets a normal **PDL**.
 
+## Classes without required constructor parameters
+
+If your class does _not_ require parameters be passed to the constructor,
+it is safe to overload the `initialize` method to return a fully fledged
+instance of your class:
+
+    sub initialize { shift->new() }
+
 ## Using with Class Frameworks
 
 The ["SYNOPSIS"](#synopsis) shows how to use **PDLx::DetachedObject** with various
@@ -86,55 +150,10 @@ always calls it, **Class::Tiny** calls it only if it inherits from
 **Class::Tiny::Object**, and **Object::Tiny** and **Class::Accessor**
 never will call the superclass' constructor.
 
-# SYNTAX
-
-### Moo
-
-    package MyPDL;
-
-    use Moo;
-    use PDL::Lite;
-
-    extends 'PDLx::DetachedObject';
-
-    has PDL => ( is => 'rw' );
-
-### Class::Tiny
-
-    package MyPDL;
-
-    use Class::Tiny qw[ PDL ];
-
-    use parent 'PDLx::DetachedObject';
-
-### Object::Tiny
-
-    package MyPDL;
-
-    use Object::Tiny qw[ PDL ];
-
-    use parent 'PDLx::DetachedObject';
-
-### Class::Accessor
-
-    package MyPDL;
-
-    use parent 'Class::Accessor', 'PDLx::DetachedObject';
-    __PACKAGE__->follow_best_practice;
-    __PACKAGE__->mk_accessors( 'PDL' );
-
-or with Antlers:
-
-    package MyPDL;
-    use Class::Accessor "antlers";
-    use parent 'PDLx::DetachedObject';
-
-    has PDL => ( is => 'ro' );
-
 # BUGS AND LIMITATIONS
 
 Please report any bugs or feature requests to
-`bug-pdlx-mask@rt.cpan.org`, or through the web interface at
+`bug-pdlx-detachedobject@rt.cpan.org`, or through the web interface at
 [http://rt.cpan.org/Public/Dist/Display.html?Name=PDLx-DetachedObject](http://rt.cpan.org/Public/Dist/Display.html?Name=PDLx-DetachedObject).
 
 # AUTHOR

cpanfile

@@ -1,7 +1,6 @@
 requires "Moo" => "0";
 requires "PDL" => "2.000";
-requires "PDL::Core" => "0";
-requires "parent" => "0";
+requires "PDL::Lite" => "0";
 requires "strict" => "0";
 requires "warnings" => "0";
 
@@ -14,10 +13,11 @@ on 'test' => sub {
   requires "IPC::Open3" => "0";
   requires "Moo" => "0";
   requires "Object::Tiny" => "0";
-  requires "PDL::Lite" => "0";
+  requires "PDL" => "2.000";
   requires "Test::Deep" => "0";
   requires "Test::More" => "0";
   requires "blib" => "1.01";
+  requires "parent" => "0";
   requires "perl" => "5.006";
 };
 

lib/PDLx/DetachedObject.pm

@@ -29,6 +29,7 @@ __END__
 
 =head3 Moo
 
+   # DEPRECATED; use MooX::PDL2 instead
    package MyPDL;
 
    use Moo;
@@ -75,10 +76,20 @@ or with Antlers:
 
 =head1 DESCRIPTION
 
-L<PDL> has a L<non-standard way of handling
-subclasses|PDL::Objects>. Because a B<PDL> object is a blessed scalar,
-outside of using inside-out classes as the subclass, there is no easy
-means of adding extra attributes to the object.
+B<PDLx::DetachedObject> provides a minimal shim between L<PDL> and
+object-orientation frameworks.  Directly subclassing B<PDL> is tricky,
+as a B<PDL> object (a piddle) is a blessed scalar, not a blessed hash.
+B<PDL> provides an L<alternate|PDL::Objects> means of subclassing; this
+class encapsulates that prescription.
+
+For L<Moo> based classes, see L<MooX::PDL2>, which provides a more
+integrated approach.
+
+=head2 Background
+
+Because a B<PDL> object is a blessed scalar, outside of using
+inside-out classes as the subclass, there is no easy means of adding
+extra attributes to the object.
 
 To work around this, B<PDL> will treat any hash blessed into a
 subclass of PDL which has an entry with key C<PDL> whose value is a
@@ -144,6 +155,14 @@ an B<initialize> class method.  The constructor ensures returns a
 properly subclassed hash with the C<PDL> key, keeping B<PDL> happy.
 When B<PDL> calls the B<initialize> function it gets a normal B<PDL>.
 
+=head2 Classes without required constructor parameters
+
+If your class does I<not> require parameters be passed to the constructor,
+it is safe to overload the C<initialize> method to return a fully fledged
+instance of your class:
+
+ sub initialize { shift->new() }
+
 =head2 Using with Class Frameworks
 
 The L</SYNOPSIS> shows how to use B<PDLx::DetachedObject> with various