[KLIB] ABI reader: Update ReadMe.md

^KT-54402

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]
+}
+```