1

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:

yard output

Community
  • 1
  • 1
Fabio
  • 18,856
  • 9
  • 82
  • 114

1 Answers1

0

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.

Douglas Camata
  • 598
  • 4
  • 10
  • Actually that's not true, see my updated question with an example also for `@method` tag. – Fabio Jul 30 '14 at 15:48
  • @Fabio 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. – Douglas Camata Jul 30 '14 at 15:55
  • @Fabio and, please, note that there's no example in Yard docs using the `@method` tag, without the `!`. – Douglas Camata Jul 30 '14 at 15:59
  • 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. – Fabio Jul 30 '14 at 16:04
  • BTW here's [an example](https://github.com/lsegal/yard/issues/431#issuecomment-3246822) written by gem owner using `@method` without `!` so I assume it's a legal Yard syntax. – Fabio Jul 30 '14 at 16:05
  • @Fabio 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. – Douglas Camata Jul 30 '14 at 16:09
  • @Fabio 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. – Douglas Camata Jul 30 '14 at 16:11
  • 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. – Fabio Jul 30 '14 at 16:40
  • @Fabio try to use `@!param` or `@!return` without using a `@!method` and see what happens. I was focussing on `@method`because it's the only with that behavior. – Douglas Camata Jul 30 '14 at 16:45
  • @Fabio 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. – Douglas Camata Jul 30 '14 at 16:54