[KLIB] ABI reader: Update ReadMe.md
^KT-54402
diff --git a/compiler/util-klib-abi/ReadMe.md b/compiler/util-klib-abi/ReadMe.md
index 5285ba6..3084477 100644
--- a/compiler/util-klib-abi/ReadMe.md
+++ b/compiler/util-klib-abi/ReadMe.md
@@ -3,5 +3,41 @@
This is the API to extract and dump declarations from KLIBs that comprise publicly visible part of KLIB ABI. Can be used for implementing various KLIB-oriented build tools that do ABI compatibility validation, perform compilation avoidance with KLIBs, etc.
There are two major entry points:
-* [LibraryAbiReader](src/org/jetbrains/kotlin/library/abi/LibraryAbiReader.kt) - extracts publicly visible ABI
-* [LibraryAbiRenderer](src/org/jetbrains/kotlin/library/abi/LibraryAbiRenderer.kt) - renders it to a human-readable textual representation
+* [LibraryAbiReader](src/org/jetbrains/kotlin/library/abi/LibraryAbiReader.kt) - extracts publicly visible ABI. The result is a loosely coupled tree (see [LibraryAbi](src/org/jetbrains/kotlin/library/abi/LibraryAbi.kt)) where the roots are the top-level declarations.
+* [LibraryAbiRenderer](src/org/jetbrains/kotlin/library/abi/LibraryAbiRenderer.kt) - renders publicly visible ABI to a human-readable textual representation.
+
+### The rendering format
+
+* A line per a declaration: `declaration_part` `//` `signature_part`
+ * `declaration_part` includes declaration keyword, modifiers and all valuable information that makes sense for ABI compatibility of the declaration.
+ * `signature_part` is just a textual representation of declaration's IR signature.
+* Declarations are always sorted in the stable order. So, changes in program order or serialization order have no effect.
+* As long as the [LibraryAbiRenderer](src/org/jetbrains/kotlin/library/abi/LibraryAbiRenderer.kt)'s output remains the same we can confidently say that the library is still ABI-compatible even if the source code was dramatically changed.
+
+Example:
+* Original *.kt file:
+```
+package org.sample
+
+class Foo<T>(var value: T?) where T : Appendable, T : List<Number> {
+ inline fun f(
+ i: Int,
+ s: String? = "hello",
+ t: T,
+ b1: () -> Unit,
+ noinline b2: (Int) -> String,
+ crossinline b3: String?.() -> Int?,
+ vararg x: Any?
+ ): Map<Long, Double>
+}
+```
+* The rendered text:
+```
+final class <#A: kotlin.collections/List<kotlin/Number> & kotlin.text/Appendable> org.sample/Foo { // org.sample/Foo|null[0]
+ final var value // org.sample/Foo.value|{}value[0]
+ final fun <get-value>(): #A? // org.sample/Foo.value.<get-value>|<get-value>(){}[0]
+ final fun <set-value>(#A?) // org.sample/Foo.value.<set-value>|<set-value>(1:0?){}[0]
+ constructor <init>(#A?) // org.sample/Foo.<init>|<init>(1:0?){}[0]
+ final inline fun f(kotlin/Int, kotlin/String? =..., #A?, kotlin/Function0<kotlin/Unit>, noinline kotlin/Function1<kotlin/Int, kotlin/String>, crossinline kotlin/Function1<kotlin/String?, kotlin/Int?>, kotlin/Array<out kotlin/Any?>...): kotlin.collections/Map<kotlin/Long, #A> // org.sample/Foo.f|f(kotlin.Int;kotlin.String?;1:0?;kotlin.Function0<kotlin.Unit>;kotlin.Function1<kotlin.Int,kotlin.String>;kotlin.Function1<kotlin.String?,kotlin.Int?>;kotlin.Array<out|kotlin.Any?>...){}[0]
+}
+```
\ No newline at end of file
