Document ValueObjAt

Author: lizmat

doc/Type/ObjAt.pod6

@@ -12,6 +12,8 @@ objects, and identify an object uniquely.
 If two objects compare equally via C<===>, their C<.WHICH> methods return
 the same ObjAt object.
 
+See also L<ValueObjAt> for value types.
+
 =end pod
 
 # vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6

doc/Type/ValueObjAt.pod6

@@ -0,0 +1,39 @@
+=begin pod
+
+=TITLE class ValueObjAt
+
+=SUBTITLE Unique identification for value types
+
+    class ValueObjAt is ObjAt { }
+
+A subclass of L<C<ObjAt>|ObjAt> that should be used to indicate that a class
+produces objects that are value types (in other words: are immutable after
+they have been initialized.
+
+    my %h = a => 42;         # mutable Hash
+    say %h.WHICH;            # ObjAt.new("Hash|1402...1161888")
+
+    my %m is Map = a => 42;  # immutable Map
+    say %m.WHICH;            # ValueObjAt.new("Map|AAF...09F61F")
+
+If you create a class that should be considered a value type, you should add
+a C<WHICH> method to that class that returns a C<ValueObjAt> object, for
+instance:
+
+    class YourClass {
+        has $.foo;  # note these are not mutable
+        has $.bar;
+
+        method WHICH() {
+            ValueObjAt.new("YourClass|$!foo|$!bar");
+        }
+    }
+
+Note that it is customary to always start the identifying string with the
+name of the object, followed by a "|".  This to prevent confusion with other
+classes that may generate similar string values: the name of the class should
+then be enough of a differentiator to prevent collisions.
+
+=end pod
+
+# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6