What's the difference between @tag and @!tag i

问题:

While looking at Yard documentation and examples sI found some tags prefixed by an exclamation mark.

I found working examples with and without exclamation marks and I wasn't able to spot the difference, so what changes when @!some-tag is used instead of @some-tag?

For instance this code generate the same documentation for both attr and attr2

class Anything
  # @!attribute [rw] attr
  # @attribute [rw] attr2
end

On the other side, in some examples the importance of exclamation mark is underlined, so it's supposed to do something, but I can't find any documentation on its usage.

@!method Example

Both these comments in a Rails model generate new methods

# @!method with_bang(param)
scope :foo_bar, where(foo: 'bar')
# @method without_bang(param)
scope :foo_baz, where(foo: 'baz')

yard output:

回答1:

The ! modifier in Yard is used when the documented piece of code will generate attributes or methods in its class. For example:

# @!method foo(name, opts = {})
create_a_foo_method

This is telling us that create_a_foo_method will generate a method with the signature def foo(name, ops = {}). You can apply this line of thinking to @!scope, @!visibility, and every other @!tag. As said in Yard documentation, this is useful for documenting DSLs.