Support for explicit public API markers

[KirpichenkovPavel]

The pull request introduces support for two new features:

• Explicit public markers. Existing properties ignoredProjects, ignoredPackages and nonPublicMarkers allow excluding some parts of API from compatibility validation and checking the rest. New publicMarkers, publicPackages and publicClasses do the opposite: if any of them is used, only explicitly marked declarations are considered for validation, all the rest are excluded.
• Adding extra Gradle source sets to check for Kotlin-JVM project. Without this change only the main source set can be validated.

Motivation

In kotlin.git we would like to maintain binary compatibility only for a few parts of the :kotlin-gradle-plugin project related to the External Kotlin Target API, that will be used by third parties when implemented. The declarations are either annotated, or belong to a specific package. Use of the existing API of validator to exclude everything else is not very convenient and would complicate maintenance of the project in the future. Because, for instance, adding new packages would require build script changes, as they have to be excluded from validation. Parts of the relevant code belong to a custom Gradle source set, so without the second introduced feature validation is not possible.

Implementation notes

• Explicit marker mode only affects validation if any of the new public* properties are used in a build script, which shouldn't affect any users that don't touch the properties
• Explicit declaration filtering happens before the usual filtering of ignored projects, packages and marked non-public declarations. This makes it possible to combine two modes, e.g. filter out marked non-public members of a class from a public package
• In case of clashes, when the same declaration is both ignored and explicitly public at the same time, ignored "wins"
• Listing extra source sets for validation is only supported for projects with the kotlin-jvm Gradle plugin to minimize the changes

[qwwdfsad]

Could you please elaborate on whether you do plan to use retainExplicitlyIncludedIfDeclared exclusively or also plugin DSL to use the API?

[qwwdfsad]

Nicely done!