Some clarifications

- don't use =foo as example, when the previous was =for, to avoid
  confusion
- separate the rakudoc from the raku parts in examples

Author: lizmat

doc/Type/RakuAST/Doc/Block.rakudoc

@@ -104,7 +104,7 @@ with $block {
 =end code
 
 Returns a L<C<Bool>|/type/Bool> indicating the block is an abbreviated block
-(aka with just C<=> followed by the type, e.g. C<=foo>).
+(aka with just C<=> followed by the type, e.g. C<=bar>).
 
 =head3 method directive
 
@@ -179,11 +179,15 @@ The C<new> method can be called to create a new C<RakuAST::Doc::Block>
 object.  It only takes named arguments, with the C<:type> argument
 being mandatory.
 
-=begin code :lang<raku>
+=begin code :lang<rakudoc>
   =begin foo
   bar
   =end foo
+=end code
+
+is equivalent to:
 
+=begin code
 my $block = RakuAST::Doc::Block.new(
   :margin("  "),
   :type<foo>,
@@ -212,7 +216,9 @@ Any config to be associated with this block, defaults to none.
 Specified as an L<C<Associative>|/type/Associative>.  Note that when specified, the
 values B<must> be C<RakuAST::> objects.  So something like:
 
-    frobnicate => 42
+=begin code
+frobnicate => 42
+=end code
 
 should be specified as:
 
@@ -252,11 +258,15 @@ Create a C<RakuAST::Doc::Block> from a number of strings to be
 considered paragraphs.  Strings are assumed to B<not> have removed
 the left margin yet.
 
-=begin code :lang<raku>
+=begin code :lang<rakudoc>
   =begin foo
   bar
   =end foo
+=end code
 
+is equivalent to:
+
+=begin code
 my $block = RakuAST::Doc::Block.from-paragraphs(
   :margin("  "),
   :type<foo>,
@@ -265,7 +275,7 @@ my $block = RakuAST::Doc::Block.from-paragraphs(
 =end code
 
 Takes the same arguments as C<new>.  Note that the paragraphs should
-only contain strings and should B<not> contain the left margin
+only contain strings and should B<also> contain the left margin
 whitespace.  A C<worry>/C<warning> will be issued if the left margin
 of a string is less than the margin indicated with C<:margin>.