[LL FIR] allow recursive access to the same FirThreadSafeCache

^KT-56721 fixed

compiler/fir/providers/src/org/jetbrains/kotlin/fir/extensions/FirDeclarationGenerationExtension.kt

@@ -23,6 +23,12 @@ import kotlin.reflect.KClass
  * TODO:
  *  - check that annotations or meta-annotations is not empty
  */
+
+/**
+ * All `generate*` members have the contract that the computation should be side-effect-free.
+ * That means that all `generate*` function implementations should not modify any state or leak the generated `FirElement` or `FirBasedSymbol` (e.g., by putting it to some cache).
+ * This restriction is imposed by the corresponding IDE cache implementation, which might retry the computation several times.
+ */
 abstract class FirDeclarationGenerationExtension(session: FirSession) : FirExtension(session) {
     companion object {
         val NAME = FirExtensionPointName("ExistingClassModification")

compiler/fir/tree/src/org/jetbrains/kotlin/fir/caches/FirCachesFactory.kt

@@ -15,6 +15,9 @@ abstract class FirCachesFactory : FirSessionComponent {
      *
      * [FirCache.getValue] should not be called inside [createValue]
      *
+     * Note, that [createValue] might be called multiple times for the same value,
+     * but all threads will always get the same value
+     *
      * Where:
      * [CONTEXT] -- type of value which be used to create value by [createValue]
      */