Core data model stabilization

[IgnatBeresnev]

This issue serves as a parent issue for stabilizing the core data model in Dokka. It includes, but is not limited to:

• The Documentable model
• The DocTag and TagWrapper models
• DokkaConfiguration and DokkaSourceSet configuration classes
• Utility classes like DokkaSourceSetID, DRI, KotlinModifier and so on.

---

Some known problems that need to be addressed:

• All documentables are data classes, which makes maintaining backward compatibility difficult. They should likely be migrated to average classes, but then there will need to be a substitution to .copy(), which is widely used in transformers
• Due to documentables being data classes, their equals and hashCode compare all properties, which is undesirable in some cases. For instance, it means that the compiler descriptors and symbols are compared transitively, which can be a heavy operation and might backfire. See Do not include sources in Documentable equals/hashCode #2620 for more details
• There's barely any documentation.
• sealed classes should be re-considered. At the moment it means all classlikes have to be in the same file and custom types cannot be added in external plugins.
• typealias SourceSetDependent<T> = Map<DokkaSourceSet, T> - here, DokkaSourceSet is used as a key, which also leads to the hashCode() and equals() comparing all of its fields, including the heavy classpath. It needs to be reconsidered, maybe it should be a map, or maybe the key should be DokkaSourceSetID. See Compare DokkaSourceSetImpl by DokkaSourceSetID only #3246 for more details
• Some information is exposed as documentable properties, while other as extra. For example, it's unclear why IsVar, IsAlsoParameter, DefaultValue, Annotations and others are extras, whereas they could be first-class properties like DClass#modifier and DFunction#isExpectActual.
• Interop with Java needs to be thought out, as at this moment it's difficult to represent some Java-specific things with the documentable model, so some information gets lost. Basically all things that differ between the languages: getters/setters, visibilities, etc. It should either have first-class support, or it should be separate from the core model, and at this moment it's neither.
• A lot of user-facing code depends on the implementations of toString(), for instance DokkaSourceSetID#toString is used directly in HTML files. DRI has a similar problem.
• Throws tag wrapper has an inconvenient name, clashes with the annotation.
• MARKDOWN_FILE magic constant is used throughout the code without any explanation for why it was chosen, with some logic and tests depending on it
• (the list is to be updated)

---

Related: #2933, #2620, #3246

[vmishenev]

Some Documentables have constrains. For example, a size of FunctionalTypeConstructor.projections should be more than zero. Need to think how to avoid having invalid Documentable.

[whyoleg]

One more candidate to address in scope: #3404