Suggestion by Jonas:
Should we not state clearly "Scala API only" for the classes that are not intended for the Java API and vice versa? Ideally we should hide it, don't think the tools support that.
We need to make sure none is favoured. Apply the least common denominator principle. Present things in a generic way if possible.
What to do with code samples for the common classes? Make sure we have both Java and Scala versions everywhere?