Original kapt was implemented in the following way...

# kapt

[alexey.tsvetkov]

Original kapt was implemented in the following way:
1. Kotlin compiler analyzes code and serializes information about annotations in some format.
2. Custom annotation processor, which is passed to javac, loads annotation data and calls other annotation processors.

Later stubs generation was added as a workaround to support references to generated code:
1. At the first step Kotlin compiler also produces class files stubs, which contain only method signatures.
2. Kotlin stubs class files are added to javac classpath. Javac performs normal Java compilation with AP.
3. Kotlin performs normal compilation (generated code is processed as any other Java/Kotlin source code).
So stubs generation allows to refer generated code in method bodies, however there are still some limitations. Note that generated code does not exist at step 1, so all references to generated code in function signatures are generated as error/NonExistentClass. If some Kotlin function signature, containing reference to generated code (as a parameter type or a return type), is processed by an annotation processor, the processor may generate reference to a NonExistentClass in generated java code. This will cause Java compilation error ('unresolved reference') which is quite hard to diagnose, because javac does not report any additional information about errors in generated Java code.

Kapt2 was an attempt to overcome that limitation. Kapt2 implements JSR 269 by wrapping Intellij platform AST. However it became apparent that Intellij platform was not optimized for such use-case, so annotation processing could be very slow in some cases.

Kapt3 is a replacement of Kapt2 implementation. Kapt3 generates javac's Java AST from Kotlin code and reuses javac's AP directly.

All in all:
* There are two kapts from a user POV: one that can generate stubs is stable, the other is next-gen, experimental and WIP.
* Kapt2 and Kapt3 are different implementations of JSR 269.
* All the differences between Kapt2 and Kapt3 are implementation details, which are not usually documented (at least not in a user documentation).