Expand docs; use an enum

crates/ruff_linter/src/rules/isort/mod.rs

@@ -182,24 +182,28 @@ fn format_import_block(
             pending_lines_before = false;
         }
 
-        let mut lines_inserted = false;
-        let mut needs_lines_inserted = false;
+        #[derive(PartialEq)]
+        enum LineInsertion {
+            Necessary,
+            Inserted,
+        }
+
+        let mut line_insertion = None;
         let mut is_first_statement = true;
         let lines_between_types = settings.lines_between_types;
         for import in imports {
             match import {
                 Import((alias, comments)) => {
-                    // Add a blank lines between direct and from imports
+                    // Add a blank lines between direct and from imports.
                     if settings.from_first
                         && lines_between_types > 0
-                        && needs_lines_inserted
-                        && !lines_inserted
+                        && line_insertion == Some(LineInsertion::Necessary)
                     {
                         for _ in 0..lines_between_types {
                             output.push_str(&stylist.line_ending());
                         }
 
-                        lines_inserted = true;
+                        line_insertion = Some(LineInsertion::Inserted);
                     }
 
                     output.push_str(&format::format_import(
@@ -210,22 +214,21 @@ fn format_import_block(
                     ));
 
                     if !settings.from_first {
-                        needs_lines_inserted = true;
+                        line_insertion = Some(LineInsertion::Necessary);
                     }
                 }
 
                 ImportFrom((import_from, comments, trailing_comma, aliases)) => {
-                    // Add a blank lines between direct and from imports
+                    // Add a blank lines between direct and from imports.
                     if !settings.from_first
                         && lines_between_types > 0
-                        && needs_lines_inserted
-                        && !lines_inserted
+                        && line_insertion == Some(LineInsertion::Necessary)
                     {
                         for _ in 0..lines_between_types {
                             output.push_str(&stylist.line_ending());
                         }
 
-                        lines_inserted = true;
+                        line_insertion = Some(LineInsertion::Inserted);
                     }
 
                     output.push_str(&format::format_import_from(
@@ -242,7 +245,7 @@ fn format_import_block(
                     ));
 
                     if settings.from_first {
-                        needs_lines_inserted = true;
+                        line_insertion = Some(LineInsertion::Necessary);
                     }
                 }
             }

crates/ruff_workspace/src/options.rs

@@ -2021,7 +2021,23 @@ pub struct IsortOptions {
     )]
     pub detect_same_package: Option<bool>,
 
-    /// Sort "from .. import .." imports before straight imports
+    /// Whether to place `import from` imports before straight imports when sorting.
+    ///
+    /// For example, by default, imports will be sorted such that straight imports appear
+    /// before `import from` imports, as in:
+    /// ```python
+    /// import os
+    /// import sys
+    /// from typing import List
+    /// ```
+    ///
+    /// Setting `from-first = true` will instead sort such that `import from` imports appear
+    /// before straight imports, as in:
+    /// ```python
+    /// from typing import List
+    /// import os
+    /// import sys
+    /// ```
     #[option(
         default = r#"false"#,
         value_type = "bool",