Updated docs/Editors.md for new system (#757)

Author: Josh Goldberg

docs/Architecture/Editors.md

@@ -1,13 +1,11 @@
 # Editors
 
-Editor lint configurations are converted by `src/converters/editorConfigs/convertEditorConfig.ts`.
-Any setting that matches a known built-in TSLint setting will be replaced with the ESLint equivalent.
+Editor lint configurations are converted by `src/converters/editorConfigs/convertEditorConfigs.ts`, which calls to a neighboring `convertEditorConfig.ts` on each file path.
 
-For now, only VS Code editor settings are accounted for.
-Eventually this will be refactored to allow other editors such as Atom.
-
-1. An existing editor configuration is read from disk.
-2. If the existing configuration is not found or errored, nothing else needs to be done.
-3. Configuration settings are converted to their ESLint equivalents.
-4. Those ESLint equivalents are written to the configuration file.
-5. Results from converting are reported to the user.
+1. Requested `--editor` paths are deduplicated into the list of file paths to convert.
+2. Each path is mapped, if possible, to its editor's converter function.
+3. Results from calling `convertEditorConfig` on that file and configuration are stored.
+    a. The requested path's contents are read from disk.
+    b. That converter function is run on the file path.
+    c. If no error occurred, the description of changed settings is reported.
+3. Results of converting are reported to the console and back to the calling code.

src/converters/editorConfigs/convertEditorConfig.ts

@@ -6,18 +6,25 @@ export type ConvertEditorConfigDependencies = {
     fileSystem: Pick<FileSystem, "readFile" | "writeFile">;
 };
 
+/**
+ * @see /docs/Editors.md for documentation.
+ */
 export const convertEditorConfig = async (
     dependencies: ConvertEditorConfigDependencies,
     converter: EditorConfigConverter,
     requestedPath: string,
     settings: TSLintToESLintSettings,
 ) => {
+    // 3a. The requested path's contents are read from disk.
     const originalFileContents = await dependencies.fileSystem.readFile(requestedPath);
     if (originalFileContents instanceof Error) {
         return originalFileContents;
     }
 
+    // 3b. That converter function is run on the file path.
     const conversion = converter(originalFileContents, settings);
+
+    // 3c. If no error occurred, the description of changed settings is reported.
     const error = await dependencies.fileSystem.writeFile(requestedPath, conversion.contents);
 
     return error ?? conversion;

src/converters/editorConfigs/convertEditorConfigs.ts

@@ -12,6 +12,10 @@ export type ConvertEditorConfigsDependencies = {
         typeof reportEditorConfigConversionResults
     >;
 };
+
+/**
+ * @see /docs/Editors.md for documentation.
+ */
 export const convertEditorConfigs = async (
     dependencies: ConvertEditorConfigsDependencies,
     settings: TSLintToESLintSettings,
@@ -20,10 +24,13 @@ export const convertEditorConfigs = async (
         failed: new Map(),
         successes: new Map(),
     };
+
+    // 1. Requested `--editor` paths are deduplicated into the list of file paths to convert.
     const requestedPaths = uniqueFromSources(settings.editor);
 
     await Promise.all(
         requestedPaths.map(async (requestedPath) => {
+            // 2. Each path is mapped, if possible, to its editor's converter function.
             const descriptor = dependencies.editorConfigDescriptors.find(([defaultPath]) =>
                 defaultPathMatches(defaultPath, requestedPath),
             );
@@ -35,6 +42,7 @@ export const convertEditorConfigs = async (
                 return;
             }
 
+            // 3. Results from calling `convertEditorConfig` on that file and configuration are stored.
             const result = await dependencies.convertEditorConfig(
                 descriptor[1],
                 requestedPath,
@@ -49,6 +57,7 @@ export const convertEditorConfigs = async (
         }),
     );
 
+    // 4. Results of converting are reported to the console and back to the calling code.
     dependencies.reportEditorConfigConversionResults(results);
 
     return results.failed.size === 0