Add documentation about some aspects of IdeaVim implementation

src/main/java/com/maddyhome/idea/vim/extension/VimExtensionRegistrar.kt

@@ -82,6 +82,31 @@ internal object VimExtensionRegistrar : VimExtensionRegistrator {
     }
   }
 
+  /**
+   * During vim initialization process, it firstly loads the .vimrc file, then executes scripts from the plugins folder.
+   * This practically means that the .vimrc file is initialized first, then the plugins are loaded.
+   * See `:h initialization`
+   *
+   * In IdeaVim we don't have a separate plugins folder to load it after .ideavimrc load. However, we can collect
+   *   the list of plugins mentioned in the .ideavimrc and load them after .ideavimrc execution is finished.
+   *
+   * Why this matters? Because this affects the order of commands are executed. For example:
+   * ```
+   * plug 'tommcdo/vim-exchange'
+   * let g:exchange_no_mappings=1
+   * ```
+   * Here the user will expect that the exchange plugin won't have default mappings. However, if we load vim-exchange
+   *    immediately, this variable won't be initialized at the moment of plugin initialization.
+   *
+   * There is also a tricky case for mappings override:
+   * ```
+   * plug 'tommcdo/vim-exchange'
+   * map X <Plug>(ExchangeLine)
+   * ```
+   * For this case, a plugin with a good implementation detects that there is already a defined mapping for
+   *   `<Plug>(ExchangeLine)` and doesn't register the default cxx mapping. However, such detection requires the mapping
+   *   to be defined before the plugin initialization.
+   */
   @JvmStatic
   fun enableDelayedExtensions() {
     delayedExtensionEnabling.forEach {

vim-engine/src/main/kotlin/com/maddyhome/idea/vim/key/RequiredShortcut.kt

@@ -12,13 +12,34 @@ import javax.swing.KeyStroke
 
 public class RequiredShortcut(public val keyStroke: KeyStroke, public val owner: MappingOwner)
 
+/**
+ * Every mapping in IdeaVim (like `map jk <esc>`) has an owner. That is needed to understand where this mapping comes
+ *   from. With that, we can, for example, remove all mappings from .ideavimrc when this file is reloaded.
+ */
 public sealed class MappingOwner {
   public interface IdeaVim {
+    /**
+     * Mapping is defined vim .ideavimrc configuration file. This doesn't always mean that the mapping is located
+     *   in this particular file, but it can be defined in the file that is loaded via source command in .ideavimrc
+     *   like `source ~/.vimrc`.
+     */
     public object InitScript : MappingOwner()
+
+    /**
+     * Mappings created during runtime. For example, when created via `:map jk <esc>` command.
+     * Also, this includes mappings that were loaded from scripts that are not .ideavimrc.
+     */
     public object Other : MappingOwner()
+
+    /**
+     * Mappings that relate to IdeaVim core. Not defined by user
+     */
     public object System : MappingOwner()
   }
 
+  /**
+   * Mappings registered from plugins
+   */
   @Suppress("DataClassPrivateConstructor")
   public data class Plugin private constructor(val name: String) : MappingOwner() {
     public companion object {