Clean up / unify meta model docs

* move several methods in the appropriate classes
* avoid duplicate descriptions between Language/objects and type docs
* document several more methods

Author: moritz

lib/Language/objects.pod

@@ -620,86 +620,7 @@ To get rid of using the same object twice, there is a shortcut:
     # same as
     say 1.HOW.name(1);                  # Int
 
-=head2 class Perl6::Metamodel::ClassHOW
-
-=SUBTITLE Meta object for a class
-
-Introspection is the process of getting information about an object or class
-at runtime. In Perl 6, all introspection goes through the meta object. The
-standard C<ClassHOW> for class-based objects offers these facilities:
-
-=head3 method can
-
-Given a method names, it returns a L<Parcel> of methods that are available
-with this name.
-
-    class A      { method x($a) {} };
-    class B is A { method x()   {} };
-    say B.^can('x').elems;              # 2
-    for B.^can('x') {
-        say .arity;                     # 1, 2
-    }
-
-In this example, class C<B> has two possible methods available with name C<x>
-(though a normal method call would only invoke the one installed in C<B>
-directly). The one in C<B> has arity 1 (i.e. it expects one argument, the
-invocant (C<self>)), and the one in C<A> expects 2 arguments (C<self> and
-C<$a>).
-
-=head3 method methods
-
-Returns a list of public methods available on the class (which includes
-methods from superclasses and roles). By default this stops at the classes
-L<Cool>, L<Any> or L<Mu>; to really get all methods, use the C<:all> adverb.
-
-    class A {
-        method x() { };
-    }
-
-    say A.^methods();                   # x
-    say A.^methods(:all);               # x infinite defined ...
-
-The returned list actually returns objects of type L<Method>, which you can
-use to introspect their signatures, and even to call them.
-
-=head3 method mro
-
-Returns the list of the class itself and its superclasses in method resolution
-order. Perl 6 linearizes the graph of superclasses into a single list that
-C<$object.^mro> returns; when a method is called, the class and its parent
-classes are visited in that order. (Only conceptually; actually the list of
-methods is built at class composition time).
-
-    say 1.^mro;                         # (Int) (Cool) (Any) (Mu)
-
-=head3 method name
-
-Returns the name of the class:
-
-    say 'a string'.^name;               # Str
-
-=head3 method parents
-
-Returns the list of parent classes. By default it stops at L<Cool>, L<Any> or
-L<Mu>, which you can suppress by supplying the C<:all> adverb. With C<:tree>,
-a nested list is returned.
-
-    class D { };
-    class C1 is D { };
-    class C2 is D { };
-    class B is C1 is C2 { };
-    class A is B { };
-
-    say A.^parents(:all).perl;          # (B, C1, C2, D, Any, Mu)
-    say A.^parents(:all, :tree).perl;
-        # ([B, [C1, [D, [Any, [Mu]]]], [C2, [D, [Any, [Mu]]]]],)
-
-=head3 method attributes
-
-Even though attributes are private to a class, you can ask a class for its
-attributes with C<$object.^attributes>. Each attribute is represented by an
-instance of the Attribute class and has attributes of its own. Of particular
-interest are C<name>, C<rw> and C<ro>, C<has_accessor>, C<type>,
-and C<package>.
+See L<Metamodel::ClassHOW|/type/Metamodel::ClassHOW> for documentation of
+the meta class of C<class>.
 
 =end pod

lib/Type/Metamodel/AttributeContainer.pod

@@ -0,0 +1,37 @@
+=begin pod
+
+=TITLE role Metamodel::AttributeContainer
+
+=SUBTITLE Meta role for holding attributes
+
+    role Metamodel::AttributeContainer { ... }
+
+Classes, roles and grammars can have attributes. Storage and introspection of
+attributes is implemented by this role.
+
+=head1 Methods
+
+=head2 method add_attribute
+
+    method add_attribute(Metamodel::AttributeContainer: $obj, $name, $attribute)
+
+Adds an attribute. C<$attribute> must be an object that supports the
+methods C<name>,  C<type> and C<package>, which are called without arguments.
+It can for example be of L<type Attribute|/type/Attribute>.
+
+=head2 method attributes
+
+    method attributes(Metamodel::AttributeContainer: $obj)
+
+Returns a list of attributes. For most Perl 6 types, these will be objects of
+L<type Attribute|/type/Attribute>.
+
+=begin comment
+
+TODO: compose_attributes, set_rw, rw, get_attribute_for_usage
+
+Also TODO: desribe :local, :excl, :all options of method attributes
+
+=end comment
+
+=end pod

lib/Type/Metamodel/ClassHOW.pod

@@ -58,4 +58,24 @@ L<of type X::Method::NotFound|/type/X::Method::NotFound> is thrown.
 User-facing code (that is, ,code not dabbling with meta classes) should use
 method C<FALLBACK> instead.
 
+=head2 method can
+
+    method can(Metamodel::ClassHOW:D: $obj, $method-name)
+
+Given a method names, it returns a L<Parcel> of methods that are available
+with this name.
+
+    class A      { method x($a) {} };
+    class B is A { method x()   {} };
+    say B.^can('x').elems;              # 2
+    for B.^can('x') {
+        say .arity;                     # 1, 2
+    }
+
+In this example, class C<B> has two possible methods available with name C<x>
+(though a normal method call would only invoke the one installed in C<B>
+directly). The one in C<B> has arity 1 (i.e. it expects one argument, the
+invocant (C<self>)), and the one in C<A> expects 2 arguments (C<self> and
+C<$a>).
+
 =end pod

lib/Type/Metamodel/MethodContainer.pod

@@ -0,0 +1,54 @@
+=begin pod
+
+=TITLE role Metamodel::MethodContainer
+
+=SUBTITLE Meta role that handles storing and introspecting methods
+
+    class Metamodel::MethodContainer { ... }
+
+roles, classes, grammars ane enums can contain methods. This role implements
+the API around storing and introspecting them.
+
+    say .name for Int.^methods(:all);
+
+    # don't do that, because it changes type Int globally.
+    # just for demonstration purposes.
+    Int.^add_method('double', method ($x:) { 2 * $x });
+    say 21.double;
+
+=head1 Methods
+
+=head2 method add_method
+
+    method add_method(Metamodel::MethodContainer: $obj, $name, $code)
+
+Adds a method to the meta class, to be called with name C<$name>.
+This should only be done before a type is composed.
+
+=head2 method methods
+
+    method methods(Metamodel::MethodContainer: $obj, :$all, :$local)
+
+Returns a list of public methods available on the class (which includes
+methods from superclasses and roles). By default this stops at the classes
+L<Cool>, L<Any> or L<Mu>; to really get all methods, use the C<:all> adverb.
+If C<:local> is set, only methods declared directly in the class are returned.
+
+    class A {
+        method x() { };
+    }
+
+    say A.^methods();                   # x
+    say A.^methods(:all);               # x infinite defined ...
+
+The returned list contains objects of type L<Method>, which you can
+use to introspect their signatures and call them.
+
+=begin comment
+
+TODO: method_table, submethod_table, declares_method, lookup, cache,
+cache_get, cache_add
+
+=end comment
+
+=end pod

lib/Type/Metamodel/MultipleInheritance.pod

@@ -0,0 +1,69 @@
+=begin pod
+
+=TITLE role Metamodel::MultipleInheritance
+
+=SUBTITLE Meta role that adds support for multiple inheritance
+
+    role Metamodel::MultipleInheritance { ... }
+
+Classes, roles and grammars can have parent classes, that is, classes to which
+method lookups fall back to, and to whose type the child class conforms to.
+
+This role implements the capability of having zero, one or more parent (or
+I<super>) classes.
+
+In addition, it supports the notion of I<hidden> classes, whose methods are
+excluded from the normal dispatching chain, so that for example C<nextsame>
+ignores it.
+
+This can come in two flavors: methods from a class marked as C<is hidden>
+are generally excluded from dispatching chains, and C<class A hides B> adds
+C<B> as a parent class to C<A>, but hides it from the method resolution order,
+so that L<mro_unhidden|/type/Metamodel::C3MRO#method mro_unhidden> skips it.
+
+=head1 Methods
+
+=head2 method add_parent
+
+    method add_parent(Metamodel::MultipleInheritance:D: $Obj, $parent, :$hides)
+
+Adds C<$parent> as a parent type. If C<$hides> is set to a true value, the
+parent type is added as a hidden parent.
+
+=head2 method parents
+
+    method parents(Metamodel::MultipleInheritance:D: $obj, :$all, :$tree)
+
+Returns the list of parent classes. By default it stops at L<Cool>, L<Any> or
+L<Mu>, which you can suppress by supplying the C<:all> adverb. With C<:tree>,
+a nested list is returned.
+
+    class D { };
+    class C1 is D { };
+    class C2 is D { };
+    class B is C1 is C2 { };
+    class A is B { };
+
+    say A.^parents(:all).perl;          # (B, C1, C2, D, Any, Mu)
+    say A.^parents(:all, :tree).perl;
+        # ([B, [C1, [D, [Any, [Mu]]]], [C2, [D, [Any, [Mu]]]]],)
+
+=head2 method hides
+
+    method hides(Metamodel::MultipleInheritance:D: $obj)
+
+Returns a list of all hidden parent classes.
+
+=head2 method hidden
+
+    method hidden(Metamodel::MultipleInheritance:D: $obj)
+
+Returns a true value if (and only if) the class is marked C<is hidden>.
+
+=head2 method set_hidden
+
+    method set_hidden(Metamodel::MultipleInheritance:D: $obj)
+
+Marks the type as hidden.
+
+=end pod