The tags for the last reader attribute of a list of attributes are ignored.

[arghous]

Description

The tags for the last reader attribute of a list of attributes are ignored.

Steps to reproduce

Test file /tmp/tst.rb:

class TwoAttrs
    #
    # @!attribute [r] attr1
    #   This first attribute.
    #   @return [String]
    #
    # @!attribute [r] attr2
    #   This second, and yet more important, attribute.
    #   @return [Integer]
    #
    attr_reader :attr1, :attr2
end

Actual Output

$ yard doc --no-private --debug /tmp/tst.rb
[debug]: Parsing ["/tmp/tst.rb"] with ruby parser
[debug]: Parsing /tmp/tst.rb
[debug]: Serializing to .yardoc/objects/root.dat
[debug]: Re-generating object ...
[debug]: Re-generating object TwoAttrs...
[debug]: Generating asset js/jquery.js
[debug]: Serializing to doc/js/jquery.js
[debug]: Generating asset js/app.js
[debug]: Serializing to doc/js/app.js
[debug]: Generating asset js/full_list.js
[debug]: Serializing to doc/js/full_list.js
[debug]: Generating asset css/style.css
[debug]: Serializing to doc/css/style.css
[debug]: Generating asset css/common.css
[debug]: Serializing to doc/css/common.css
[debug]: Generating asset css/full_list.css
[debug]: Serializing to doc/css/full_list.css
[debug]: Generating asset class_list.html
[debug]: Serializing to doc/class_list.html
[debug]: Generating asset method_list.html
[debug]: Serializing to doc/method_list.html
[debug]: Generating asset file_list.html
[debug]: Serializing to doc/file_list.html
[debug]: Generating asset frames.html
[debug]: Serializing to doc/frames.html
[debug]: Serializing to doc/index.html
[debug]: Serializing to doc/_index.html
[debug]: Serializing to doc/top-level-namespace.html
[debug]: Serializing to doc/TwoAttrs.html
Files: 1
Modules: 0 ( 0 undocumented)
Classes: 1 ( 1 undocumented)
Constants: 0 ( 0 undocumented)
Attributes: 2 ( 0 undocumented)
Methods: 0 ( 0 undocumented)
66.67% documented

Note: If I replace 'attr_reader' with 'attr_accessor' (and replace '[r]' with '[rw]'), the behavior is as expected.

Expected Output

Instead of "#attr2 -> Object" it should read "#attr2 -> Integer" and instead of "Returns the value of attribute attr2" is should read "The second, and yet more important, attribute".

Environment details:

• OS: $ uname -a
  Linux oroshi 2.6.32-696.13.2.el6.x86_64 attr_reader registers as RW #1 SMP Fri Sep 22 12:32:14 EDT 2017 x86_64 x86_64 x86_64 GNU/Linux
• Ruby version: $ ruby -v
  ruby 2.2.3p173 (2015-08-18 revision 51636) [x86_64-linux]
• YARD version: $ yard -v
  yard 0.9.9

Also tested with Ruby 2.4:

• Ruby version: $ ruby -v
  ruby 2.4.2p198 (2017-09-14 revision 59899) [x86_64-linux]

I have read the Contributing Guide.

[lsegal]

See #1126 for information on how to document attributes. You should not be using @!attribute here.

[arghous]

Um, O.K., I guess.

I'll have to split up my attribute declarations to one per line... I had to do something similar with RDoc; modifying my code to appease RDoc is one of the reasons why I'm no longer using RDoc.

It might be good in the attr_* documentation (e.g. http://www.rubydoc.info/gems/yard/file/docs/Tags.md#attr_reader) to link to that basic text (http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md#Documenting_Attributes), as others will likely get confused as did I. Thanks.

[lsegal]

Any source-based documentation tool will rely to some degree on the formatting you use to document code. Ruby is even more complicated in this regard because of how malleable the grammar is. There are many idioms that YARD simply can't parse. YARD tries to keep that list minimal and promote best practices.

The longer answer is that you can make @!attribute work in your case if you really wanted to, but that directive is not meant for this use case. Fundamentally, you should attempt to avoid YARD features if you can represent something in literal idiomatic Ruby code. The whole Ruby idiom of "declarations are code and code are declarations" should apply to your docs. This minimizes duplication.

I should add here that YARD's goals are not in line with the blanket concept of allowing any documentation to be applied to Ruby source with zero required source formatting changes. In fact, quite the opposite: just like in Ruby itself, syntax and formatting are meant to have semantic effect on readability, and, therefore, documentation of a Ruby codebase.

Also worth noting that separating the attr_*s makes your docs more concise in this case, too:

# @return [String] the first attribute
attr_reader :attr1

# @return [Integer] the second, and yet more important, attribute
attr_reader :attr2

You're right, though, @!attribute definitely needs documentation to steer users in the right place and explain the intent and use cases of the directive.

[arghous]

Thanks. Sorry if I was too snarky. I think YARD is a terrific tool and find it very useful. There's a learning curve for everything. I may disagree that splitting attribute definitions across lines is more idiomatic, but can see the benefits of doing so when integrating with tools like YARD.