KLIB reader: comments added (#1937)

extracted/konan.metadata/build.gradle

@@ -1,3 +1,5 @@
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: drop this module completely!
+
 buildscript {
     ext.rootBuildDirectory = file('../..')
 

extracted/konan.serializer/build.gradle

@@ -1,3 +1,5 @@
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: drop this module completely!
+
 buildscript {
     ext.rootBuildDirectory = file('../..')
 

extracted/konan.serializer/src/org/jetbrains/kotlin/serialization/konan/KonanResolvedModuleDescriptorsFactory.kt

@@ -11,6 +11,18 @@ interface KonanResolvedModuleDescriptorsFactory {
 
     val moduleDescriptorFactory: KonanDeserializedModuleDescriptorFactory
 
+    /**
+     * Given the [resolvedLibraries] creates the list of [ModuleDescriptorImpl]s with properly installed
+     * inter-dependencies. The result of this method is returned in a form of [KonanResolvedModuleDescriptors] instance.
+     *
+     * Please use this method with care: Unless this method accepts `null` for [builtIns], it is not recommended to
+     * invoke it this way. If you are compiling a source module, please supply the non-null [builtIns] from the
+     * source module, so that all modules created in your compilation session will share the same built-ins instance.
+     *
+     * Otherwise (if `null` was supplied), a new instance of [KotlinBuiltIns] will be created. The created built-ins
+     * instance will be shared by all modules created in this method. But this instance will have no connection
+     * with probably existing built-ins instance of your source module(s).
+     */
     fun createResolved(
             resolvedLibraries: KonanLibraryResolveResult,
             storageManager: StorageManager,
@@ -22,6 +34,11 @@ interface KonanResolvedModuleDescriptorsFactory {
 
 class KonanResolvedModuleDescriptors(
 
+        /**
+         * The list of modules each representing an individual Kotlin/Native library. All modules
+         * in this list have properly installed dependencies, i.e. module has all necessary dependencies
+         * on other modules plus a dependency on the [forwardDeclarationsModule].
+         */
         val resolvedDescriptors: List<ModuleDescriptorImpl>,
 
         /**