Fix: Don't link to undocumented types in API docs

[spuun]

Fixes #9816

[spuun]

Maybe it would make more sense to pass type to these *_with_docs methods…

[straight-shoota]

Maybe it would make more sense to pass type to these *_with_docs methods…

Why? What would that improve? If they're instance methods on TypeTemplate and type is an instance variable, why would we pass it as method parameter?

[spuun]

Maybe it would make more sense to pass type to these *_with_docs methods…

Why? What would that improve? If they're instance methods on TypeTemplate and type is an instance variable, why would we pass it as method parameter?

To make it clear in the html template from where the types are fetched, but maybe one should understand that from the context.

[straight-shoota]

I see. Maybe it could make sense to move the *_with_docs methods to Type. But then we wouldn't have access to types.
So I think this is fine as it is. We can always refactor later.

[ysbaddaden]

I understand @Sija's feeling: I liked the type.subclasses notation that was a little more explicit (i.e. I want the subclasses of type). We can't do that because we need types from the template, and filtering in the template sounds like the correct place... so what about a filter method, for example with_docs(type.subclasses)?

Now this is nitpicking and the PR can be merged as-is 👍

[Blacksmoke16]

I noticed while looking into the latest comment on #12018, that this PR may have changed more than we expected?

Before:

After:

The Crystal::System::* and IO::Evented make sense because those were :nodoc:, but the other like IO::FileDescriptor I would have expected to remain given they're public?

I can move this to its own issue if this is indeed a regression.

[straight-shoota]

Yeah, that doesn't seem to work correctly. I believe types only contains the top-level types (see Generator#collect_subtypes).

[spuun]

I believe the filtering must be done in Doc::Type instead? I see it's done in Doc::Type#subclasses but not in #ancestors, #included_modules or #extended_modules. I'll give it another try including specs.

[straight-shoota]

This patch was eventually reverted in #14908 due to #14878 (comment)