Add a yieldself tag

lib/yard/tags/library.rb

@@ -593,6 +593,14 @@ def directive_create(tag_name, tag_buf, parser)
       # @see tag:return
       define_tag "Yield Returns",      :yieldreturn, :with_types
 
+      # Documents the type of context in which the block is expected
+      # to run.
+      #
+      # @example
+      #   # @yieldself [Array] An array will evaluate the block
+      #   def add5_block(&block) [].instance_eval(&block) end
+      define_tag "Yield Self",         :yieldself, :with_types
+
       # @yard.signature [r | w | rw] attribute_name
       #   Indented attribute docstring
       define_directive :attribute, :with_types_and_title, AttributeDirective
@@ -624,7 +632,7 @@ def directive_create(tag_name, tag_buf, parser)
       define_directive :visibility,                       VisibilityDirective
 
       self.visible_tags = [:abstract, :deprecated, :note, :todo, :example, :overload,
-        :param, :option, :yield, :yieldparam, :yieldreturn, :return, :raise,
+        :param, :option, :yield, :yieldparam, :yieldself, :yieldreturn, :return, :raise,
         :see, :author, :since, :version]
 
       self.transitive_tags = [:since, :api]

spec/templates/examples/tag001.txt

@@ -42,6 +42,11 @@ Yield Parameters:
 
     (String) a - a value
 
+Yield Self:
+-----------
+
+    (Object) - an object
+
 Yield Returns:
 --------------
 

spec/templates/tag_spec.rb

@@ -23,6 +23,7 @@
         # @version 1.0
         # @yield a block
         # @yieldparam [String] a a value
+        # @yieldself [Object] an object
         # @yieldreturn [Hash] a hash
         # @example Wash your car
         #   car.wash