Apply :nodoc: to nested classes and modules [ci-skip]

[jonathanhefner]

When :nodoc: is applied to a class / module, RDoc will still document nested classes / modules, unless :nodoc: is applied to them as well. Additionally, if :nodoc: all is applied to a class / module that contains nested classes / modules, like so:

class Foo # :nodoc: all
  def foo_method; end

  class Bar
    def bar_method; end
  end
end

RDoc will still include the outer class / module (e.g. Foo) in the doc index, albeit as an empty namespace. Furthermore, SDoc will include both outer and inner (e.g. Foo and Bar) in the index as empty namespaces.

However, when :nodoc: is applied at all levels, like so:

class Foo # :nodoc:
  def foo_method; end

  class Bar # :nodoc:
    def bar_method; end
  end
end

Both RDoc and SDoc include neither outer nor inner in the index.

[matthewd]

Is that expected behaviour of :nodoc: all? Feels like a bug to me.

[jonathanhefner]

Is that expected behaviour of :nodoc: all? Feels like a bug to me.

It might be. I wasn't planning to dig into it, but if someone wants to tackle it, I can convert this PR to apply :nodoc: all instead.

[p8]

SDoc is still pinned to an older version of RDoc:
zzak/sdoc@9ee2184
We could drop support for Ruby < 2.5 in SDoc, so it'll be more in sync with RDoc.

[jonathanhefner]

@p8 Do you know if that would avoid including both Foo and Bar (from my example) in the doc index?

I originally did try to diagnose whether the issue was from RDoc or SDoc. When I used just RDoc v6.3.3 without SDoc (via the rdoc bin), I saw Foo in the index (without any methods), but not Bar. When I used SDoc (via rake rdoc), I saw both Foo and Bar in the index (both without any methods).

[jonathanhefner]

Now that we have updated to SDoc v2.3.2 (#44932), I have tried with RDoc v6.4.0, but the issue is still present.

@matthewd Do you object to me merging this PR?

[zzak]

FWIW, it seems RDoc intentionally leaves nested classes/modules as documented even when using :nodoc: all:
https://github.com/ruby/rdoc/blob/9c03b6e586f4016dbdb3bacebde1ef86dda9cc11/doc/rdoc/markup_reference.rb#L472-L477

# - <tt># :nodoc: all</tt>:
#
#   - Appended to a line of code
#     that defines a class or module.
#   - Specifies that the class or module should not be documented.
#     By default, however, a nested class or module _will_ be documented.