perlclass: work out the initial document structure

.mailmap

@@ -156,6 +156,7 @@ Bah <bah@longitude.com> bah@longitude.com <bah@longitude.com>
 Barrie Slaymaker <barries@slaysys.com> root <root@jester.slaysys.com>
 Bart Kedryna <bkedryna@home.com> <bkedryna@home.com>
 Bart Kedryna <bkedryna@home.com> bart@cg681574-a.adubn1.nj.home.com <bart@cg681574-a.adubn1.nj.home.com>
+Bartosz Jarzyna <bbrtj.pro@gmail.com> bbrtj <bbrtj.pro@gmail.com>
 Beau Cox <unknown> beau@beaucox.com <beau@beaucox.com>
 Ben Carter <bcarter@gumdrop.flyinganvil.org> Benjamin Carter <q.eibcartereio.=~m-b.{6}-cgimosx@gumdrop.flyinganvil.org>
 Ben Morrow <ben@morrow.me.uk> mauzo@csv.warwick.ac.uk <mauzo@csv.warwick.ac.uk>

AUTHORS

@@ -155,6 +155,7 @@ Barrie Slaymaker               <barries@slaysys.com>
 Barry Friedman
 Bart Kedryna                   <bkedryna@home.com>
 Bart Van Assche                <bvanassche@acm.org>
+Bartosz Jarzyna                <bbrtj.pro@gmail.com>
 Bas van Sisseren               <bas@quarantainenet.nl>
 Beau Cox
 Ben Carter                     <bcarter@gumdrop.flyinganvil.org>

pod/perlclass.pod

@@ -1,79 +1,218 @@
 =head1 NAME
 
-perlclass - Perl class syntax
+perlclass - Perl class syntax reference
 
-=head1 DESCRIPTION
+=head1 SYNOPSIS
 
     use v5.36;
     use feature 'class';
 
     class My::Example 1.234 {
         field $x;
-        ADJUST { $x = "Hello, world"; }
 
-        method print_message { say $x; }
+        ADJUST {
+            $x = "Hello, world";
+        }
+
+        method print_message {
+            say $x;
+        }
     }
 
     My::Example->new->print_message;
 
-C<class> is like C<package>. Classes automatically get a C<new> method; you
-don't have to (and should not) write one.
+=head1 DESCRIPTION
 
-C<method> is like C<sub> but automatically gains a C<$self> lexical.
+This document describes the syntax of the Perl's C<class> feature, which
+provides native keywords supporting object-oriented programming paradigm.
 
-C<ADJUST> blocks run during construction and are the way to add code that runs
-during the construction time of each instance. They also have a C<$self>
-lexical.
+=head2 History
 
-C<field> is like C<my> but only visible within C<methods> and C<ADJUST>
-blocks.
+Since Perl 5, support for objects resolved around the concept of I<blessing>
+references with a package name. Such reference could then be used to call
+subroutines from the package it was blessed with (or any of its parents). This
+system, while bare-bones, was flexible enough to allow creation of multiple
+more advanced, community-driven systems for object orientation.
 
-Instances get their own value storage for fields
+Class feature is a core implementation of class syntax which is familiar to
+what one would find in other programming languages. It isn't a C<bless>
+wrapper, but a completely new system built right into the perl interpreter.
 
-    class My::Counter {
-        field $count; ADJUST { $count = 0; }
+=head1 KEYWORDS
 
-        method incr { $count++ }
-        method val  { return $count; }
+Enabling the C<class> feature allows the usage of the following new keywords in
+the scope of current package:
+
+=head2 class
+
+    class NAME BLOCK
+
+    class NAME VERSION BLOCK
+
+    class NAME;
+
+    class NAME VERSION;
+
+The C<class> keyword declares a new package which is intended to be a class.
+All other keywords from the C<class> feature should be used in scope of this
+declaration.
+
+    class WithVersion 1.000 {
+        # class definition goes here
     }
 
-    my $ca = My::Counter->new;
-    $ca->incr; $ca->incr; $ca->incr;
+Classes can be declared in either block or statement syntax. If a block is
+used, the body of the block contains the implementation of the class. If the
+statement form is used, the remainder of the file is used up until the next
+C<class> or C<package> statement.
 
-    my $cb = My::Counter->new;
-    $cb->incr;
+C<class> and C<package> declarations are similar, but classes automatically get
+a constructor named C<new> - You don't have to (and should not) write one.
+Additionally, in the class BLOCK you are allowed to declare fields and methods.
 
-    say "Counter A is at ", $ca->val;
-    say "Counter B is at ", $cb->val;
+=head2 field
 
-C<methods> always act as if C<use feature 'signatures'> is in effect. You do
-not need to worry about the C<$self> lexical: it is automatically created and
-populated with the object instance, which will not appear in the arguments
-list as far as the signature is concerned.
+    field VARIABLE_NAME;
 
-    class Example::WithSignatures {
-        method greet($name = "someone") {
-            say "Hello, $name";
+Fields are variables which are visible in the scope of the class - more
+specifically within L</method> and C<ADJUST> blocks. Each class instance get
+their own storage of fields, independent of each other.
+
+A field behaves like a normal lexically scoped variable. It has a sigil and is
+private to the class (though creation of an accessor method will make it
+accessible from the outside). The main difference is that different instances
+access different values in the same scope.
+
+    class WithFields {
+        field $scalar;
+        field @array;
+        field %hash;
+
+        ADJUST {
+            $scalar = 42;
+            @array = qw(this is just an array);
+            %hash = (species => 'Marsian', planet => 'Mars');
         }
     }
 
+=head2 method
+
+    method METHOD_NAME SIGNATURE BLOCK
+
+    method METHOD_NAME BLOCK
+
+    method SIGNATURE BLOCK
+
+    method BLOCK
+
+Methods are subroutines intended to be called in the context of class objects.
+
+A variable named C<$self> populated with the current object instance will
+automatically be created in the lexical scope of C<method>.
+
+Methods always act as if C<use feature 'signatures'> is in effect, but C<$self>
+will not appear in the arguments list as far as the signature is concerned.
+
+    class WithMethods {
+        field $greetings;
+
+        ADJUST {
+            $greetings = "Hello";
+        }
+
+        method greet($name = "someone") {
+            say "$greetings, $name";
+        }
+    }
+
+Just like regular subroutines, methods I<can> be anonymous:
+
+    class AnonMethodFactory {
+
+        method get_anon_method {
+            return method {
+                return 'this is an anonymous method';
+            };
+        }
+    }
+
+=head1 ATTRIBUTES
+
+Specific aspects of the keywords mentioned above are managed using
+I<attributes>. Attributes all start with a colon, and one or more of them can
+be appended after the item's name, separated by a space.
+
+=head2 Class attributes
+
+=head3 :isa
+
 Classes may inherit from B<one> superclass, by using the C<:isa> class
 attribute.
 
-  class Example::Base { ... }
+    class Example::Base { ... }
 
-  class Example::Subclass :isa(Example::Base) { ... }
+    class Example::Subclass :isa(Example::Base) { ... }
 
 Inherited methods are visible and may be invoked. Fields are always lexical
-and therefore not visible by inheritence.
+and therefore not visible by inheritance.
 
 The C<:isa> attribute may request a minimum version of the base class; it is
-applied similar to C<use>; if the provided version is too low it will fail at
+applied similar to C<use> - if the provided version is too low it will fail at
 compile time.
 
-  class Example::Subclass :isa(Example::Base 2.345) { ... }
+    class Example::Subclass :isa(Example::Base 2.345) { ... }
 
 The C<:isa> attribute will attempt to C<require> the named module if it is not
 already loaded.
 
+=head2 Field attributes
+
+None yet.
+
+=head2 Method attributes
+
+None yet.
+
+=head1 OBJECT LIFECYCLE
+
+=head2 Construction
+
+Each object begins its life with a constructor call. The constructor is always
+named C<new> and is invoked like a method call on the class name:
+
+    my $object = My::Class->new(%arguments);
+
+During the construction, class fields are compared to C<%arguments> hash and
+populated where possible.
+
+=head2 Adjustment
+
+Object adjustment can be performed during the construction to run user-defined
+code. It is done with the help of C<ADJUST> blocks, which are called in order
+of declaration.
+
+They are similar to C<BEGIN> blocks, which run during the compilation of a
+package. However, they also have access to C<$self> lexical (object instance)
+and all object fields created up to that point.
+
+=head2 Lifetime
+
+After the construction phase, object is ready to be used.
+
+Using C<blessed> (C<Scalar::Util::blessed> or C<builtin::blessed>) on the
+object will return the name of the class, while C<reftype>
+(C<Scalar::Util::reftype> or C<builtin::reftype>) will return the string
+C<'OBJECT'>.
+
+=head2 Destruction
+
+Just like with other references, when object reference count reaches zero it
+will automatically be destroyed.
+
+=head1 AUTHORS
+
+Paul Evans
+
+Bartosz Jarzyna
+
 =cut