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>,
 
         /**

shared/build.gradle

@@ -34,6 +34,7 @@ repositories {
     }
 }
 
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: drop generation of KonanVersion!
 task generateCompilerVersion(type: VersionGenerator){}
 
 sourceSets {

shared/src/main/kotlin/org/jetbrains/kotlin/konan/MetaVersion.kt

@@ -16,6 +16,8 @@
 
 package org.jetbrains.kotlin.konan
 
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: remove the whole file!
+
 /**
  *  https://en.wikipedia.org/wiki/Software_versioning
  *  scheme major.minor[.build[.revision]].

shared/src/main/kotlin/org/jetbrains/kotlin/konan/VisibleNamed.kt

@@ -16,6 +16,8 @@
 
 package org.jetbrains.kotlin.konan.util
 
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: remove the whole file!
+
 val <T : Enum<T>> T.visibleName get() = name.toLowerCase() 
 interface Named {
     val name: String

shared/src/main/kotlin/org/jetbrains/kotlin/konan/file/File.kt

@@ -16,6 +16,8 @@
 
 package org.jetbrains.kotlin.konan.file
 
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: remove the whole file!
+
 import java.io.BufferedReader
 import java.io.InputStream
 import java.io.InputStreamReader

shared/src/main/kotlin/org/jetbrains/kotlin/konan/library/SearchPathResolver.kt

@@ -6,17 +6,20 @@ import org.jetbrains.kotlin.konan.target.KonanTarget
 import org.jetbrains.kotlin.konan.util.removeSuffixIfPresent
 import org.jetbrains.kotlin.konan.util.suffixIfNot
 
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: remove the constants below:
 const val KLIB_FILE_EXTENSION = "klib"
 const val KLIB_FILE_EXTENSION_WITH_DOT = ".$KLIB_FILE_EXTENSION"
 
 const val KONAN_STDLIB_NAME = "stdlib"
 
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: remove this interface!
 interface SearchPathResolver {
     val searchRoots: List<File>
     fun resolve(givenPath: String): File
     fun defaultLinks(noStdLib: Boolean, noDefaultLibs: Boolean): List<File>
 }
 
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: remove this interface!
 interface SearchPathResolverWithTarget: SearchPathResolver {
     val target: KonanTarget
 }

shared/src/main/kotlin/org/jetbrains/kotlin/konan/target/KonanTarget.kt

@@ -16,6 +16,8 @@
 
 package org.jetbrains.kotlin.konan.target
 
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: remove the whole file!
+
 import org.jetbrains.kotlin.konan.target.KonanTarget.*
 import org.jetbrains.kotlin.konan.util.Named
 import java.io.Serializable

shared/src/main/kotlin/org/jetbrains/kotlin/konan/target/Properties.kt

@@ -16,6 +16,8 @@
 
 package org.jetbrains.kotlin.konan.properties
 
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: remove the whole file!
+
 import org.jetbrains.kotlin.konan.file.*
 
 typealias Properties = java.util.Properties

shared/src/main/kotlin/org/jetbrains/kotlin/konan/util/Substitution.kt

@@ -3,6 +3,8 @@ package org.jetbrains.kotlin.konan.util
 import org.jetbrains.kotlin.konan.target.KonanTarget
 import java.util.*
 
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: remove the whole file!
+
 fun defaultTargetSubstitutions(target: KonanTarget) =
         mapOf<String, String>(
             "target" to target.visibleName,

shared/src/main/kotlin/org/jetbrains/kotlin/konan/util/Util.kt

@@ -19,6 +19,7 @@ package org.jetbrains.kotlin.konan.util
 import kotlin.system.measureTimeMillis
 import org.jetbrains.kotlin.konan.file.*
 
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: remove this function:
 fun printMillisec(message: String, body: () -> Unit) {
     val msec = measureTimeMillis{
         body()
@@ -26,10 +27,12 @@ fun printMillisec(message: String, body: () -> Unit) {
     println("$message: $msec msec")
 }
 
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: remove this function:
 fun profile(message: String, body: () -> Unit) = profileIf(
     System.getProperty("konan.profile")?.equals("true") ?: false,
     message, body)
 
+// FIXME(ddol): KLIB-REFACTORING-CLEANUP: remove this function:
 fun profileIf(condition: Boolean, message: String, body: () -> Unit) =
     if (condition) printMillisec(message, body) else body()