Configuration: document how imports sorting works

Author: kitbellew

docs/configuration.md

@@ -3610,6 +3610,16 @@ or selector, as follows:
 
 > Since v3.0.0.
 
+Let's define some terminology: an import statement consists of several parts:
+
+- keyword: `import` or `export`
+- one or more comma-separated _importers_
+  - for instance, `import foo.bar, foo.baz.{qux => quux}` contains two
+    importers, `foo.bar` and `foo.baz.{qux => quux}`
+- each importer is split, on the final dot, into
+  - _reference_: `foo` and `foo.baz` in the example above
+  - _selectors_: `bar` and `{qux => quux}` above
+
 #### Imports: `expand`
 
 This parameter will attempt to create a separate line for each selector
@@ -3637,6 +3647,21 @@ import a.{
   }
 ```
 
+#### Imports: sorting
+
+Sorting is applied as follows:
+
+- if disabled, no sorting
+- if enabled, it applies to import _selectors_ within one _importer_
+- if [`groups`](#imports-groups) are used, sorting will also apply to importers
+  in the same group
+  - without groups, multiple import statements will **not** be sorted
+  - importers are sorted one dot-separated label at a time
+    - importers `foo.bar.baz` and `foo.bar as fbar` will compare:
+      - `foo` and `foo`: equal
+      - `bar` and `bar as fbar`: `bar` comes earlier, just like it does
+        with equivalent scala2 selector syntax `{bar => fbar}`
+
 #### Imports: `sort = none`
 
 This default option causes no sorting.
@@ -3697,8 +3722,9 @@ import foo._
 > rule like `OrganizeImports`. However, on a large codebase, the overhead
 > of using semantic `scalafix` rules might be substantial.
 
-This rule will separate all import statements into groups. If sorting is
-enabled (i.e., not `none`), imports will also be sorted within each group.
+This rule will separate all import statements (or, to be more precise, all
+[importers](#imports) from all import statements) into groups. If sorting
+is enabled (i.e., not `none`), imports will also be sorted within each group.
 
 The rule accepts the following parameters:
 
@@ -3715,13 +3741,15 @@ The rule accepts the following parameters:
     (source, package, template etc.)
 
 ```scala mdoc:scalafmt
+runner.dialect = scala3
 rewrite.rules = [Imports]
 rewrite.imports.sort = ascii
 rewrite.imports.groups = [
   ["foo\\..*"],
   ["bar\\..*", "baz\\..*"]
 ]
 ---
+import bar.bar as bbar
 import bar.bar.{Random, bar, ~>, `symbol`}
 import baz.Baz.{bar => xyz, _}
 import qux.`qux`.{Random, bar, ~>, `symbol`}