Add warning in doc generator when doc comment is overriden

[straight-shoota]

When types are reopened, there can be multiple doc comments for the same thing:

# Foo
class Foo
end

# Foo class
class Foo
end

Only one of them is used by the docs generator (I think it's the latter?) and the other is simply overridden. This is not desired behaviour. It doesn't make sense to simply concatenate the docs either. There should ever be only a single place for documentation a single feature. So when generating docs, the compiler could show a warning when doc has been defined before. Alternatively, it could directly fail, but I think a warning is fine.

This would avoid issues like #8337

[asterite]

Yes! I had the same idea in the past but I forgot to turn it into an issue or PR.

[RX14]

It should either fail or override. Compiler warnings should be avoided.

[straight-shoota]

@RX14 What about deprecation warnings?

We could deprecate this at first and make it fail in the next release. I'm fine with failing directly, though. It's trivial to fix so won't be a big hold up when doc generation fails because of this.

We should however decide whether doc errors like this should only fail the doc generator or also the compiler (i.e. should it be a syntax error?). I don't think this needs to affect the compiler. Programs with documentation errors should still be able to compile.

[RX14]

Deprecations are the only kind of warnings the compiler should provide, imo. I've been working to make them less verbose too (I've stated my vision for the deprecations UX many times before) but the code is a quagmire and unfortunately I'm really busy ;_;

Ary said a long time ago that crystal didn't have compiler warnings because either the feature had a usecase - or it should be explicitly disallowed with a compiler error. I still agree. Linters exist to fill the usecase of opinionated "this isn't best practice" - not the compiler.

Since the language and is changing before 1.0, removing and changing features, we also have to generate deprecation warnings for language changes. This will be unneccesary after 1.0 (because we can't remove language features), and deprecations will only be issued for @[Deprecated] annotations.

[bcardiff]

I think in this case we are discussing a warning / output in the doc generator tool. And not in the compiler itself.

Something like:

hey! you might want to add a blank line if you don't want the comment to be a doc

could be a good suggestion.

[straight-shoota]

I'd prefer to make overriding documentation a failure, either only for the doc generator or maybe even a generic syntax error.

[nobodywasishere]

Could we have the docs just merged together in the order they're parsed?

[straight-shoota]

That would be pretty confusing and have weird effects. There should ever be only a single place for documentating a single feature.