@!attribute documentation not working as expected

[MaxPleaner]

Given a class like this:

class TwitterWrapper
  # @!attribute [r] client
  #   @return [Twitter::REST::Client]
  attr_reader :client
end

and I use YARD 0.9.9 to generate docs, I see the wrong return type:

Yet when I use just @return:

class TwitterWrapper
  # @return [Twitter::REST::Client]
  attr_reader :client
end

it works fine:

I also tried @attr [Twitter::REST::Client] but it still showed Object.

I am using Bash on Ubuntu on Windows 10. Ruby version 2.4.2

[zverok]

It is because YARD finds two attr definitions:

  # definition 1: with directive and return type
  # @!attribute [r] client
  #   @return [Twitter::REST::Client]

  # definition 2: naturally, and without return type
  attr_reader :client

The second one rewrites the first.

If you'll try this:

class TwitterWrapper
  # @!attribute [r] client
  #   @return [Twitter::REST::Client]
end

...everything would be OK.

[zverok]

!@attribute directive is used when YARD can't see attrs from code (when they are defined with metaprogramming), otherwise you should not use it.

[MaxPleaner]

Thank you for the explanation. It might be useful to have a note about this in the YARD's own YARD docs for attribute.

[zverok]

It is general idea for directives (things with @!) -- they are necessary when something can not be guessed from code. Written at the very beginning of the Tags.md:

Directives are similar to meta-data tags in the way they are specified, but they do not add meta-data to the object directly. Instead, they affect the parsing context and objects themselves, allowing a developer to create objects (like methods) outright, rather than simply add text to an existing object. Directives have a @! prefix to differentiate these tags from meta-data tags, as well as to indicate that the tag may modify or create new objects when it is called.

[lsegal]

You should not use @!attribute if you have an attr_* statement. See the guide documentation on documenting attributes:

http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md#Documenting_Attributes