Warn when :nodoc: appears on standalone line

[Kerrick]

I misused :nodoc: and spent time debugging before finding my error. This patch adds a warning for others who might do the same.

The problem:

class Foo
  VISIBLE_CONST = :hello

  # :nodoc:
  HIDDEN_CONST = :bar

  def visible_method
  end
end

I expected only the constant to be hidden. Instead, visible_method also disappeared from my documentation.

The documentation says :nodoc: should be appended inline. This works correctly:

HIDDEN_CONST = :bar # :nodoc:

Since the standalone form is accepted silently but produces surprising results, this patch emits a warning when the pattern is detected.

I am glad to adjust the implementation or wording. If this does not fit RDoc's direction, please close it.

---

This issue includes creative contributions from Claude (Anthropic).

[tompng]

Standalone :nodoc: is valid and used correctly. We cant just warn for standalone :nodoc:.

class A
  # :nodoc:

  def undocumented1; end

  def undocumented2; end
end

These :nodoc: are misused, so it can be warned.

class A
  ...

  # :nodoc:
  def f1; end

  # :nodoc:
  # comment for f2

  def f2; end
end

I think checking this is not possible from handle_directive's argument.
Instead of warning, maybe there's an option to change the :nodoc: behavior. I've filed an issue #1578

[Kerrick]

Thank you!