Add :showdoc: directive for private and protected objects (RFC #0011)

[nobodywasishere]

First part of splitting up #15294.

Private class:

Private methods:

[ysbaddaden]

I've just been thinking of an edge case: we need the parent namespace to appear if any descendant type is marked with :showdoc: but will any documentation following :nodoc: be shown?

# :nodoc:
# 
# this comment musn't appear in docs
module Foo
  # :showdoc:
  #
  # this comment must appear in docs
  module Bar
  end
end

[straight-shoota]

@ysbaddaden I believe the nodoc nesting showdoc case should be handled because #must_include? checks for :nodoc: in parent namespaces.

But this concern brings up that there should be specs for this to ensure the behaviour is implemented as inspected and won't change by future changes.
Granted, the doc generator specs are not very extensive. But that only means we need to write more tests, not less. I believe there should be ample existing examples that can be adapted to add relevant examples for testing this change.

[nobodywasishere]

@ysbaddaden I believe the behavior determined during discussion with the RFC is that a :showdoc: inside a :nodoc: would prevent the showdoc from working.

@straight-shoota I can work on adding doc generator specs.

[nobodywasishere]

https://forum.crystal-lang.org/t/rfc-extending-api-docs-and-compiler-semantic-output/7314/21

[nobodywasishere]

Let me know if you have more ideas for specs

[crysbot]

This pull request has been mentioned on Crystal Forum. There might be relevant details there:

https://forum.crystal-lang.org/t/win32cr-1-0-release/7630/2

[ysbaddaden]

Thank you! That looks all good to me.