Enforce Javadoc comment quality

[slarse]

Poking around in the metamodel interfaces, I've noticed that many of them lack proper documentation of parameters and return types.

I think we should enforce that public methods and constructors are properly documented. Checkstyle can do this with the JavadocMethod module. The problem is that it raises ~2600 errors when activated on the public scope alone, so obviously this needs to be introduced gradually. I'm thinking we can add a script that computes a penalty (the amount of errors), and if the penalty increases in relation to the master branch, we break the build. This doesn't entirely guard against poorly documented methods as one could e.g. remove an error from one javadoc and introduce a new one somewhere else, but it's pretty good and pretty easy to implement.

Good docs are important to me, so I'm gonna give this a shot. Decreasing the penalty can then be a great first issue, much like #3854.

[monperrus]

👍 In Spoon, we love high-quality documentation, esp. in the API.