docs: add comments for configuration handling and conflict resolution in importer and exporter

Author: xinnjie

internal/plugins/vscode/export.go

@@ -88,6 +88,20 @@ func newExporterWithEditorType(
 	}
 }
 
+// Export (GenerateEditorConfig) generates VSCode keybindings from the keymap setting.
+//
+// Handling Existing Configurations:
+// It reads the existing VSCode configuration (if provided via opts.ExistingConfig) to identify
+// "unmanaged" keybindings—those not maintained by OneKeymap. These are preserved to support
+// a non-destructive export/update process.
+//
+// Conflict Resolution:
+//   - Managed keybindings (generated from KeymapSetting) take precedence over conflicting
+//     unmanaged keybindings from the existing configuration.
+//   - If a keybinding in the existing configuration uses the same key combination as a
+//     managed one, the managed one overwrites it.
+//   - The final list is re-ordered to respect the command order of the existing configuration,
+//     preserving the user's preferred organization where possible.
 func (e *vscodeLikeExporter) Export(
 	_ context.Context,
 	destination io.Writer,

internal/plugins/vscode/import.go

@@ -45,7 +45,14 @@ func newImporterWithEditorType(
 	}
 }
 
-// Import reads a VSCode keybindings.json file and converts it to a universal KeymapSetting.
+// Import (AnalyzeEditorConfig) reads a VSCode keybindings.json file and converts it to a universal KeymapSetting.
+//
+// Handling Existing Configurations:
+// It parses the VSCode JSON configuration from the source, handling comments and trailing commas.
+//
+// Conflict Resolution:
+// - Unknown commands or unparsable keys are skipped and tracked in the validation report.
+// - Duplicate actions resulting from the import are deduplicated to ensure a clean result.
 func (i *vscodeLikeImporter) Import(
 	ctx context.Context,
 	source io.Reader,

pkg/api/exporterapi/exporter.go

@@ -13,7 +13,17 @@ import (
 // into an editor-specific format.
 type Exporter interface {
 	// Export converts a KeymapSetting and writes it to a destination stream.
-	// It returns a report detailing any issues encountered during the conversion.
+	//
+	// Handling Existing Configurations:
+	// It reads existing configuration from the input stream (if provided via opts.OriginalConfig)
+	// to identify user-defined or unmanaged keybindings that should be preserved.
+	//
+	// Conflict Resolution:
+	// - Managed keybindings (generated from KeymapSetting) take precedence over conflicting
+	//   unmanaged keybindings from the existing configuration.
+	// - The final output attempts to respect the structure or order of the existing configuration
+	//   where applicable.
+	// - A report is returned detailing the changes (diff) and any issues encountered.
 	Export(
 		ctx context.Context,
 		destination io.Writer,

pkg/api/importerapi/importer.go

@@ -12,8 +12,16 @@ import (
 // Importer defines the interface for the import service, which handles the
 // conversion of editor-specific keymaps into the universal format.
 type Importer interface {
-	// Import converts keymaps from a source stream. It returns the converted
-	// settings and a report detailing any conflicts or unmapped actions.
+	// Import (corresponding to AnalyzeEditorConfig logic) converts keymaps from a source stream.
+	//
+	// Handling Existing Configurations:
+	// It reads configuration from the input stream (e.g., editor specific config like keybindings.json)
+	// and analyzes it to map keybindings to the universal format.
+	//
+	// Conflict Resolution:
+	// - Conflicts during conversion (e.g., multiple keybindings mapping to the same action)
+	//   are resolved by the implementation, typically by deduplicating actions.
+	// - Any unmapped actions or ambiguities are reported in the ImportResult.
 	Import(ctx context.Context, opts ImportOptions) (*ImportResult, error)
 }