WIP: Tiny initial hack at some documentation

Author: leonerd

MANIFEST

@@ -5298,6 +5298,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

@@ -265,6 +265,7 @@ L<C<last>|/last LABEL>, L<C<__LINE__>|/__LINE__>,
 L<C<next>|/next LABEL>, L<C<__PACKAGE__>|/__PACKAGE__>,
 L<C<redo>|/redo LABEL>, L<C<return>|/return EXPR>,
 L<C<sub>|/sub NAME BLOCK>, L<C<__SUB__>|/__SUB__>,
+L<C<method>|/method NAME BLOCK>,
 L<C<wantarray>|/wantarray>
 
 L<C<break>|/break> is available only if you enable the experimental
@@ -295,7 +296,8 @@ current scope.
 
 L<C<caller>|/caller EXPR>, L<C<import>|/import LIST>,
 L<C<local>|/local EXPR>, L<C<my>|/my VARLIST>, L<C<our>|/our VARLIST>,
-L<C<package>|/package NAMESPACE>, L<C<state>|/state VARLIST>,
+L<C<package>|/package NAMESPACE>, L<C<class>|/class NAMESPACE>, 
+L<C<field>|/field VARNAME>, L<C<state>|/state VARLIST>,
 L<C<use>|/use Module VERSION LIST>
 
 L<C<state>|/state VARLIST> is available only if the
@@ -345,7 +347,9 @@ X<object> X<class> X<package>
 
 L<C<bless>|/bless REF,CLASSNAME>, L<C<dbmclose>|/dbmclose HASH>,
 L<C<dbmopen>|/dbmopen HASH,DBNAME,MASK>,
-L<C<package>|/package NAMESPACE>, L<C<ref>|/ref EXPR>,
+L<C<package>|/package NAMESPACE>, L<C<class>|/class NAMESPACE>,
+L<C<field>|/field VARNAME>, L<C<method>|/method NAME BLOCK>,
+L<C<ref>|/ref EXPR>,
 L<C<tie>|/tie VARIABLE,CLASSNAME,LIST>, L<C<tied>|/tied VARIABLE>,
 L<C<untie>|/untie VARIABLE>, L<C<use>|/use Module VERSION LIST>
 
@@ -427,6 +431,7 @@ L<C<time>|/time>, L<C<times>|/times>
 =for Pod::Functions =!Non-functions
 
 C<and>,
+C<ADJUST>,
 C<AUTOLOAD>,
 C<BEGIN>,
 C<catch>,
@@ -1278,6 +1283,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>
 
@@ -2749,6 +2769,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>
 
@@ -4313,6 +4342,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>
 
@@ -10571,4 +10610,12 @@ documented in L<perlsyn/"defer blocks">.
 
 =back
 
+=over
+
+=item ADJUST
+
+This class-related phaser block is documented in L<perlclass>.
+
+=back
+
 =cut