WIP: Tiny initial hack at some documentation

Author: leonerd

MANIFEST

@@ -5299,6 +5299,7 @@ pod/perlboot.pod
 pod/perlbot.pod			
 pod/perlcall.pod		Perl calling conventions from C
 pod/perlcheat.pod		Perl cheat sheet
+pod/perlclass.pod		Perl class syntax
 pod/perlclib.pod		Internal replacements for standard C library functions
 pod/perlcommunity.pod		Perl community information
 pod/perldata.pod		Perl data structures

pod/perlclass.pod

@@ -0,0 +1,60 @@
+=head1 NAME
+
+perlclass - Perl class syntax
+
+=head1 DESCRIPTION
+
+    use v5.36;
+    use feature 'class';
+
+    class My::Example 1.234 {
+        field $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.
+
+C<method> is like C<sub> but automatically gains a C<$self> lexical.
+
+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.
+
+C<field> is like C<my> but only visible within C<methods> and C<ADJUST>
+blocks.
+
+Instances get their own value storage for fields
+
+    class My::Counter {
+        field $count; ADJUST { $count = 0; }
+
+        method incr { $count++ }
+        method val  { return $count; }
+    }
+
+    my $ca = My::Counter->new;
+    $ca->incr; $ca->incr; $ca->incr;
+
+    my $cb = My::Counter->new;
+    $cb->incr;
+
+    say "Counter A is at ", $ca->val;
+    say "Counter B is at ", $cb->val;
+
+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.
+
+    class Example::WithSignatures {
+        method greet($name = "someone") {
+            say "Hello, $name";
+        }
+    }
+
+=cut

pod/perlfunc.pod

@@ -1278,6 +1278,21 @@ may be outside of the new root.
 
 Portability issues: L<perlport/chroot>.
 
+=item class NAMESPACE
+
+=item class NAMESPACE VERSION
+
+=item class NAMESPACE BLOCK
+
+=item class NAMESPACE VERSION BLOCK
+
+=for Pod::Functions declare a separate global namespace that is an object class
+
+Declares the BLOCK or the rest of the compilation unit as being in the given
+namespace, which implements an object class.  This behaves similarly to
+L<C<package>/package NAMESPACE>, except that the newly-created package behaves
+as a class.
+
 =item close FILEHANDLE
 X<close>
 
@@ -2739,6 +2754,15 @@ A special token that returns the name of the file in which it occurs.
 It can be altered by the mechanism described at
 L<perlsyn/"Plain Old Comments (Not!)">.
 
+=item field VARNAME
+X<field>
+
+=for Pod::Functions declare a field variable of the current class
+
+Declares a new field variable within the current class.  Methods and
+L<C<ADJUST>/BLOCK> blocks of the class will have access to this variable as
+if it was a lexical in scope at that point.
+
 =item fileno FILEHANDLE
 X<fileno>
 
@@ -4303,6 +4327,16 @@ or to force an anon hash constructor use C<+{>:
 
 to get a list of anonymous hashes each with only one entry apiece.
 
+=item method NAME BLOCK
+X<method>
+
+=item method NAME : ATTRS BLOCK
+
+=for Pod::Functions declare a method of a class
+
+Creates a new named method in the scope of the class that it appears within.
+This is only valid inside a L<C<class>/class NAMESPACE> declaration.
+
 =item mkdir FILENAME,MODE
 X<mkdir> X<md> X<directory, create>
 
@@ -10561,4 +10595,12 @@ documented in L<perlsyn/"defer blocks">.
 
 =back
 
+=over
+
+=item ADJUST
+
+This class-related phaser block is documented in L<perlclass>.
+
+=back
+
 =cut