FIR2IR: add comments about translation phases

compiler/fir/fir2ir/src/org/jetbrains/kotlin/fir/backend/Fir2IrClassifierStorage.kt

@@ -190,7 +190,10 @@ class Fir2IrClassifierStorage(
         return result
     }
 
+    // Note: this function is called exactly once, right after Fir2IrConverter finished f/o binding for regular classes
     fun processMembersOfClassesCreatedOnTheFly() {
+        // After the call of this function, members of local classes may be processed immediately
+        // Before the call it's not possible, because f/o binding for regular classes isn't done yet
         processMembersOfClassesOnTheFlyImmediately = true
         for ((klass, irClass) in localClassesCreatedOnTheFly) {
             processMembersOfClassCreatedOnTheFly(klass, irClass)

compiler/fir/fir2ir/src/org/jetbrains/kotlin/fir/backend/Fir2IrConverter.kt

@@ -393,17 +393,27 @@ class Fir2IrConverter(
             // Necessary call to generate built-in IR classes
             externalDependenciesGenerator.generateUnboundSymbolsAsDependencies()
             classifierStorage.preCacheBuiltinClasses()
+            // The file processing is performed phase-to-phase:
+            //   1. Creation of all non-local regular classes
+            //   2. Class header processing (type parameters, supertypes, this receiver)
             for (firFile in allFirFiles) {
                 converter.processClassHeaders(firFile)
             }
+            //   3. Class member (functions/properties/constructors) processing. This doesn't involve bodies (only types).
+            //   If we encounter local class / anonymous object in signature, then (1) and (2) is performed immediately for this class,
+            //   and (3) and (4) a bit later
             for (firFile in allFirFiles) {
                 converter.processFileAndClassMembers(firFile)
             }
+            //   4. Override processing which sets overridden symbols for everything inside non-local regular classes
             for (firFile in allFirFiles) {
                 converter.bindFakeOverridesInFile(firFile)
             }
+            //   Do (3) and (4) for local classes encountered during (3)
             classifierStorage.processMembersOfClassesCreatedOnTheFly()
 
+            //   5. Body processing
+            //   If we encounter local class / anonymous object here, then we perform all (1)-(5) stages immediately
             for (firFile in allFirFiles) {
                 firFile.accept(fir2irVisitor, null)
             }