What's the difference between @tag and @!tag in Yard documentation tool?

Question

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:

Panada

Answer 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.

Societal

Actually that's not true, see my updated question with an example also for @method tag. – Panada

@Panada that's because of the behavior of the @method tag. Pay attention to this line extracted from Yard docs: Note that YARD uses the first argument in the method call to determine the method name. In some cases, this would not be the method name, and you would need to declare it manually. You can do so with the @!method directive. Try to do the same with tags like @return or @param. Theoretically, without the ! you're telling that the code bellow is a method named without_bang, not that it generates a method without_bang in the class. – Societal

@Panada and, please, note that there's no example in Yard docs using the @method tag, without the !. – Societal

note that both @method and @!method work in the same way in my example. The note you posted is about generic @method usage, it's not about ! usage. – Panada

BTW here's an example written by gem owner using @method without ! so I assume it's a legal Yard syntax. – Panada

@Panada they might work in the same way, but they don't have the same meaning and may generate different HTML in the future, if @method is intended to be working this way and not because of the lack of tests that it shouldn't work. – Societal

@Panada that example is years old, you won't find any recent example using just @method. That note in yard doc is describing the usage of @!method. And I repeat: there's nothing about using @method in Yard documentation. – Societal

you're focusing on @method tag, but the question is valid for other tags as well. There are two possible answers: either non bang tags are still allowed for backward compatibility or they do have some meaning. – Panada

@Panada try to use @!param or @!return without using a @!method and see what happens. I was focussing on @methodbecause it's the only with that behavior. – Societal

@Panada I already explained it to you, bang tags are used to describe methods dynamically generated in classes, non-bang tags are used to describe the method below them. The @method is the only one with that different behavior. – Societal