With our enhanced Kotlin support we now understand the way things look in Kotlin, and not just how they look in Java. This means we can do stuff like hide Kotlin internal types even though they appear as public when decompiled in Java.

internal class MyClass { }

This is correct and is automatically doing "The Right Thing". However, a user may not actually want "The Right Thing" done. Because Java exposes internal Kotlin classes and methods as public, there seems to be many cases in the wild where the types are used by consuming Java code despite the original intention.

This means there are cases where users do want to bind Kotlin internal things. The ideal scenario would be they could write a metadata transform to override visibility, just like they can do with Java types/members. But these Kotlin fixups are done in class-parse and not generator, and thus it cannot be fixed with metadata. In fact, there is currently no way to "fix" this scenario other than changing the Kotlin code and recompiling. (Users often do not have this ability and are simply using a 3rd party .jar.)

Proposal

Extend our api.xml format to allow visibility='kotlin-internal'.

Today, class-parse marks internal members as private, which prevents class-parse from emitting them. Instead, we should allow them to be emitted with visibility='kotlin-internal'. Once in the api.xml, this would give users a chance to change the visibility to public if desired:

<attr path="/api/package[@name='com.example']/class[@name='MyClass']" name="visibility">public</attr>

generator would be modified to ignore kotlin-internal members when importing the api.xml file. (This happens after the XPath transforms are performed on the metadata file so user modifications will be taken into account.)