Small rephrasing about coercion.

Also define the example class Bar at the beginning of the example, there is
no point here to leave it abstract.

Author: fluca1978

doc/Language/functions.pod6

@@ -906,43 +906,51 @@ say LoggedVersion.new('1.0.2');
 
 =head1 Coercion Types
 
-Coercion types can help you to have a specific type inside a routine, but
-accept wider input. When the routine is called, the argument is automatically
-converted to the narrower type.
+Coercion types force a specific type for routine arguments while allowing
+the routine itself to accept a wider input. When invoked, the arguments are
+narrowed automatically to the stricter type, and therefore within the routine
+the arguments have always the desired type.
+
+In the case the arguments cannot be converted to the stricter type, a I<Type Check> error
+is thrown.
 
 =begin code
 sub double(Int(Cool) $x) {
     2 * $x
 }
 
 say double '21';    # OUTPUT: «42␤»
+say double  21;     # OUTPUT: «42␤»
 say double Any;     # Type check failed in binding $x; expected 'Cool' but got 'Any'
 =end code
 
-Here, the C<Int> is the target type to which the argument will be coerced, and
-C<Cool> is the type that the routine accepts as input.
+In the above example, the L<Int|/type/Int> is the target type to which the argument C<$x> will be coerced, and
+L<Cool|/type/Cool> is the type that the routine accepts as wider input.
 
-If the accepted input type is L<Any|/type/Any>, you can abbreviate C<Int(Any)>
-to C<Int()>.
+If the accepted wider input type is L<Any|/type/Any>, it is possible to abbreviate the coercion C<Int(Any)>
+omitting the C<Any> type, thus resulting in  C<Int()>.
 
 The coercion works by looking for a method with the same name
-as the target type. You can define coercions for your own types like so:
+as the target type: if such method is found on the argument, it is invoked to
+convert the latter to the expected narrow type.
+From the above, it is clear that it is possible to provide coercion among user types
+just providing the required methods:
 
 =begin code
-class Bar {...}
+class Bar {
+   has $.msg;
+}
 
 class Foo {
    has $.msg = "I'm a foo!";
 
+   # allows coercion from Foo to Bar
    method Bar {
        Bar.new(:msg($.msg ~ ' But I am now Bar.'));
    }
 }
 
-class Bar {
-   has $.msg;
-}
-
+# wants a Bar, but accepts Any
 sub print-bar(Bar() $bar) {
    say $bar.^name; # OUTPUT: «Bar␤»
    say $bar.msg;   # OUTPUT: «I'm a foo! But I am now Bar.␤»
@@ -951,9 +959,15 @@ sub print-bar(Bar() $bar) {
 print-bar Foo.new;
 =end code
 
+In the above code, once a C<Foo> instance is passed as argument to C<print-bar>, the C<Foo.Bar>
+method is called and the result is placed into C<$bar>.
+
 Coercion types are supposed to work wherever types work, but Rakudo currently
 (2017.05) only implements them in signatures, for both parameters and return types.
 
+=comment is the above referencing rakudo 2017.05 still valid?
+=comment is it worth placing an example about return types?
+
 =head1 sub MAIN
 
 X<|MAIN>X<|command line arguments>