From 00fb9276244519d22f9e3f54e93235b5a0f0d27b Mon Sep 17 00:00:00 2001
From: Dmitriy Dolovov <Dmitriy.Dolovov@jetbrains.com>
Date: Fri, 4 Aug 2023 02:16:58 +0200
Subject: [PATCH] [KLIB] ABI reader: Update ReadMe.md

^KT-54402
---
 compiler/util-klib-abi/ReadMe.md | 40 ++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/compiler/util-klib-abi/ReadMe.md b/compiler/util-klib-abi/ReadMe.md
index 5285ba6db42..3084477e7f3 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