More documentation, more test cases, more black

Author: amyreese

crates/ruff_python_formatter/resources/test/fixtures/black/cases/import_comments.py

@@ -5,6 +5,26 @@
 from x import a as b  # comment
 from x import a as b, b as c  # comment
 
+from x import (
+    a,  # comment
+)
+from x import (
+    a,  # comment
+    b,
+)
+
+# ensure comma is added
+from x import (
+    a  # comment
+)
+
+# follow black style by merging cases without own-line comments
+from x import (
+    a  # alpha
+    ,  # beta
+    b,
+)
+
 # ensure intermixed comments are all preserved
 from x import (  # one
     # two

crates/ruff_python_formatter/resources/test/fixtures/black/cases/import_comments.py.expect

@@ -5,6 +5,25 @@ from x import a, b  # comment
 from x import a as b  # comment
 from x import a as b, b as c  # comment
 
+from x import (
+    a,  # comment
+)
+from x import (
+    a,  # comment
+    b,
+)
+
+# ensure comma is added
+from x import (
+    a,  # comment
+)
+
+# follow black style by merging cases without own-line comments
+from x import (
+    a,  # alpha  # beta
+    b,
+)
+
 # ensure intermixed comments are all preserved
 from x import (  # one
     # two

crates/ruff_python_formatter/src/comments/placement.rs

@@ -1925,7 +1925,7 @@ fn handle_bracketed_end_of_line_comment<'a>(
     CommentPlacement::Default(comment)
 }
 
-/// Attach an enclosed end-of-line comment to a [`ast::StmtImportFrom`].
+/// Attach an enclosed comment to a [`ast::StmtImportFrom`].
 ///
 /// For example, given:
 /// ```python
@@ -1936,6 +1936,33 @@ fn handle_bracketed_end_of_line_comment<'a>(
 ///
 /// The comment will be attached to the [`ast::StmtImportFrom`] node as a dangling comment, to
 /// ensure that it remains on the same line as the [`ast::StmtImportFrom`] itself.
+///
+/// If the comment's preceding node is an alias, and the comment is *before* a comma:
+/// ```python
+/// from foo import (
+///     bar as baz  # comment
+///     ,
+/// )
+/// ```
+///
+/// The comment will then be attached to the [`ast::Alias`] node as a dangling comment instead,
+/// to ensure that it retains its position before the comma.
+///
+/// Otherwise, if the comment is *after* the comma or before a following alias:
+/// ```python
+/// from foo import (
+///     bar as baz,  # comment
+/// )
+///
+/// from foo import (
+///     bar,
+///     # comment
+///     baz,
+/// )
+/// ```
+///
+/// Then it will retain the default behavior of being attached to the relevant [`ast::Alias`] node
+/// as either a leading or trailing comment.
 fn handle_import_from_comment<'a>(
     comment: DecoratedComment<'a>,
     import_from: &'a ast::StmtImportFrom,
@@ -1974,7 +2001,7 @@ fn handle_import_from_comment<'a>(
             .skip_trivia()
             .next()
         {
-            // treat comments before the comma as dangling, after as trailing (default)
+            // Treat comments before the comma as dangling, after as trailing (default)
             if let Some(AnyNodeRef::Alias(alias)) = comment.preceding_node() {
                 CommentPlacement::dangling(alias, comment)
             } else {
@@ -1986,6 +2013,27 @@ fn handle_import_from_comment<'a>(
     }
 }
 
+/// Attach an enclosed comment to the appropriate [`ast::Identifier`]  within an [`ast::Alias`].
+///
+/// For example:
+/// ```python
+/// from foo import (
+///     bar  # comment
+///     as baz,
+/// )
+/// ```
+///
+/// Will attach the comment as a trailing comment on the first name [`ast::Identifier`].
+///
+/// Wheras:
+/// ```python
+/// from foo import (
+///     bar as  # comment
+///     baz,
+/// )
+/// ```
+///
+/// Will attach the comment as a leading comment on the second name [`ast::Identifier`].
 fn handle_alias_comment<'a>(
     comment: DecoratedComment<'a>,
     alias: &'a ruff_python_ast::Alias,

crates/ruff_python_formatter/src/other/alias.rs

@@ -19,6 +19,13 @@ impl FormatNodeRule<Alias> for FormatAlias {
         write!(f, [DotDelimitedIdentifier::new(name)])?;
 
         let comments = f.context().comments().clone();
+
+        // ```python
+        // from foo import (
+        //     bar  # comment
+        //     as baz,
+        // )
+        // ```
         if comments.has_trailing(name) {
             write!(
                 f,
@@ -32,8 +39,14 @@ impl FormatNodeRule<Alias> for FormatAlias {
         }
 
         if let Some(asname) = asname {
-            write!(f, [token("as"),])?;
+            write!(f, [token("as")])?;
 
+            // ```python
+            // from foo import (
+            //     bar as  # comment
+            //     baz,
+            // )
+            // ```
             if comments.has_leading(asname) {
                 write!(
                     f,
@@ -49,15 +62,43 @@ impl FormatNodeRule<Alias> for FormatAlias {
             write!(f, [asname.format()])?;
         }
 
-        if comments.has_dangling(item) {
-            write!(
-                f,
-                [
-                    trailing_comments(comments.dangling(item)),
-                    hard_line_break()
-                ]
-            )?;
+        // Dangling comment between alias and comma on a following line
+        // ```python
+        // from foo import (
+        //     bar  # comment
+        //     ,
+        // )
+        // ```
+        let dangling = comments.dangling(item);
+        if !dangling.is_empty() {
+            write!(f, [trailing_comments(comments.dangling(item))])?;
+
+            // Black will move the comma and merge comments if there is no own-line comment between
+            // the alias and the comma.
+            //
+            // Eg:
+            // ```python
+            // from foo import (
+            //     bar  # one
+            //     ,  # two
+            // )
+            // ```
+            //
+            // Will become:
+            // ```python
+            // from foo import (
+            //     bar,  # one  # two)
+            // ```
+            //
+            // Only force a hard line break if an own-line dangling comment is present.
+            if dangling
+                .iter()
+                .any(|comment| comment.line_position().is_own_line())
+            {
+                write!(f, [hard_line_break()])?;
+            }
         }
+
         Ok(())
     }
 }