Update documentation for yield_self and then

The example usage for `then` was mistakenly placed next to `yield_self`.

kernel.rb

@@ -117,6 +117,15 @@ module Kernel
   #     # does not meet condition, drop value
   #     2.then.detect(&:odd?)            # => nil
   #
+  #  Good usage for +then+ is value piping in method chains:
+  #
+  #     require 'open-uri'
+  #     require 'json'
+  #
+  #     construct_url(arguments).
+  #       then {|url| URI(url).read }.
+  #       then {|response| JSON.parse(response) }
+  #
   def then
     unless block_given?
       return Primitive.cexpr! 'SIZED_ENUMERATOR(self, 0, 0, rb_obj_size)'
@@ -132,15 +141,6 @@ module Kernel
   #
   #     "my string".yield_self {|s| s.upcase }   #=> "MY STRING"
   #
-  #  Good usage for +then+ is value piping in method chains:
-  #
-  #     require 'open-uri'
-  #     require 'json'
-  #
-  #     construct_url(arguments).
-  #       then {|url| URI(url).read }.
-  #       then {|response| JSON.parse(response) }
-  #
   def yield_self
     unless block_given?
       return Primitive.cexpr! 'SIZED_ENUMERATOR(self, 0, 0, rb_obj_size)'