From 0791678b07c0ee212da560b2cb832f579e9b51f3 Mon Sep 17 00:00:00 2001
From: dylwil3 <dylwil3@gmail.com>
Date: Mon, 8 Dec 2025 13:35:01 -0600
Subject: [PATCH] add some doc-comments

---
 .../ruff_python_formatter/src/expression/mod.rs  | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/crates/ruff_python_formatter/src/expression/mod.rs b/crates/ruff_python_formatter/src/expression/mod.rs
index 5a166c2535..9d4faf5842 100644
--- a/crates/ruff_python_formatter/src/expression/mod.rs
+++ b/crates/ruff_python_formatter/src/expression/mod.rs
@@ -878,6 +878,20 @@ impl<'a> First<'a> {
 ///     )
 /// ).all()
 /// ```
+///
+/// In `preview`, we also track the position of the leftmost call or
+/// subscript on an attribute in the chain and break just before the dot.
+///
+/// So, for example, we would get:
+/// ```python
+///     Blog.objects
+///     .filter(
+///         entry__headline__contains="Lennon",
+///     ).filter(
+///         entry__pub_date__year=2008,
+///     )
+/// ```
+/// in the first summand above, and similarly in the second.
 #[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
 pub enum CallChainLayout {
     /// The root of a call chain
@@ -891,6 +905,8 @@ pub enum CallChainLayout {
     NonFluent,
 }
 
+/// Records information about the position of a call chain
+/// element relative to the first call or subscript.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AttributeState {
     CallsOrSubscriptsPreceding(u32),