Add a yieldself tag

[castwide]

Description

Add a @yieldself tag to document the context in which yielded blocks are expected to run. Example:

class Foo; end

class Bar
  def initialize
    @foo = Foo.new
  end

  # @yieldself [Foo]
  def run_in_foo &proc
    @foo.instance_eval &proc
  end
end

Solargraph currently uses this tag to enhance autocompletion. I was planning to write an extension so gems could add it to their yardocs, but it seemed useful enough in documentation to check if it was worth adding to YARD itself.

Completed Tasks

• I have read the Contributing Guide.
• The pull request is complete (implemented / written).
• Git commits have been cleaned up (squash WIP / revert commits).
• I wrote tests and ran bundle exec rake locally (if code is attached to PR).

[lsegal]

I realize this is a little late, but the naming for this is a little confusing. At first I thought this was specifying that the block (literally) "yields self", which I would have suggested is already supported. Upon further reading, this is actually about the type of self. I could see a few people tripping up on this, especially since the tag description does not make it any more obvious.

I'm not sure what the right solution is, but I think in its current form I'm not too keen on merging. I'd suggest either a better name (no, I don't have a good answer here), or, at the very least, a more descriptive name parameter in the define_tag declaration so that readers understand what the field is.

tl;dr documentation authors might understand what @yieldself is (the docs provide the context), but readers of the generated docs will just see "yield self" and have no idea what that means.

[castwide]

@lsegal Thanks for your feedback. I see what you mean about the name being confusing. Do you think @yieldreceiver would make more sense?

[lekemula]

@castwide is just throwing another suggestion here - how about: @yieldbinding? It would tie well with the Binding concept.