Documentation followed by annotation comments

[agrimm]

Currently, the following code creates a Documentation offense:

# Does fooing.
# FIXME: Not yet implemented.
class Foo
  def initialize
  end
end

This offense can be avoided by putting the FIXME line (the annotation comment) first.

Is this deliberate, or unintentional?

I assume that the annotation comment is about the implementation, while the non-annotation comment is about interface/intention, and that the latter is more likely to be relevant to someone reading the file. Therefore, non-annotation comments should appear first.

[bbatsov]

Seems like a bug to me. I guess the intention was to exclude comment annotations from class/module documentation. @jonas054 should know more about this.

[jonas054]

Yes, it's bug. It should be the other way around IMO so that

# Does fooing.
# FIXME: Not yet implemented.
class Foo

is accepted, but

# FIXME: Not yet implemented.
# Does fooing.
class Foo

is not. It's very difficult to judge where the annotation ends, so I want to call the whole comment an annotation if the first line has an annotation keyword.

[jonas054]

I just saw that or own OneLineConditional does not live up to my new definition:
https://github.com/bbatsov/rubocop/blob/master/lib/rubocop/cop/style/one_line_conditional.rb#L6-L7

It would be confusing for users to get the Missing top-level class documentation comment report in such cases. Some more explanation would be needed in the message.

So I'm thinking now that we should abondon the idea of trying to disregard the annotation comments in this cop, and just accept any comment. What do you think, @bbatsov @yujinakayama @agrimm?

[bbatsov]

@jonas054 Guess we can assume annotation comments are one line long.

[jonas054]

@bbatsov Good idea. I've done so in the PR now.