Instance attribute summary and details handle multi-line @!attribute declarations differently, and confusingly

[dmolesUC]

Given the following code:

# Minimal bug demonstration
#
# @!attribute [r] good
#   @return [String] This attribute has all of its documentation on the same line as the type list.
# @!attribute [r] bad
#   @return [String] This attribute has multiple lines of documentation, and
#   the first line (the text after the type list) gets lost. But subsequent
#   lines all seem to come through OK.
class YardocBug
  attr_reader :good
  attr_reader :bad
  def initialize(good, bad)
    @good = good
    @bad = bad
  end
end

I'd expect the documentation for both attributes to be complete in both sections. However, in the "Instance Attribute Summary" section, while the first attribute (good) is fine, the second attribute (bad) loses the text "This attribute has multiple lines of documentation, and" on the @return line, and also loses everything after the . in the second line:

Meanwhile, in the "Instance attribute details" section, while good is again fine, bad has its text split out, so the text on the @return line is in the Returns section, and the rest of the text is in the main docstring -- and missing the generated text "Returns":

The "Multi-line Tags" section of the docs does mention in passing that @!attribute is one of the tags/directives that assign a special meaning to the first line, but the @!attribute section itself doesn't explain what or how.

It's possible most of this could be addressed by additional documentation (including perhaps a multi-line @!attribute example), but (1) it seems like the return value description would be a better choice for the summary than the first sentence of the rest of the docstring, and (2) the fact that it's the first sentence, rather than say the entire line, is pretty surprising.

(This is with yard 0.8.7.6 on Ruby 2.2.1.)

[lsegal]

This definitely looks like a bug either in the DocstringParser or the Docstring#summary method, or both. I don't think this is related to the @!attribute directive specifically.

[lsegal]

It took me a while to get back around to this, but this is actually not a bug and working as intended. I accidentally missed the important part of this issue: subsequent lines of a tag's text must be indented to be associated with the tag (in the same way you correctly indented the @!attribute text). In this case, because the 2nd line is not indented, it is treated as regular docstring text, which becomes the initial text for the object. Following that logic, the return tag text contains only the first line, which it correctly displays. Using @return as your first tag made diagnosing this more confusing, because YARD uses the @return tag text as the docstring if no plain docstring text is in the object. Had this been any other tag, the issue would have been more obvious.

Indenting the subsequent lines fixes this. I missed the lack of indentation when I read through this the first time. Sorry about that!

[dmolesUC]

Thanks, @lsegal — I'm not quite following your explanation, though (sorry, it's a while since I thought about this issue, too). So would the correct formatting be as follows?

# @!attribute [r] bad
#   @return [String] This attribute has multiple lines of documentation, and
#     the second line is indented an additional two spaces.

Or should it be this?

# @!attribute [r] bad
#   @return [String] 
#     This attribute has multiple lines of documentation, and
#     both lines are separate from the `return' tag and indented.