Enable `--document-private-items` for `ruff_python_formatter` (#21903)

.github/workflows/ci.yaml

@@ -298,7 +298,7 @@ jobs:
       # sync, not just public items. Eventually we should do this for all
       # crates; for now add crates here as they are warning-clean to prevent
       # regression.
-      - run: cargo doc --no-deps -p ty_python_semantic -p ty -p ty_test -p ruff_db --document-private-items
+      - run: cargo doc --no-deps -p ty_python_semantic -p ty -p ty_test -p ruff_db -p ruff_python_formatter --document-private-items
         env:
           # Setting RUSTDOCFLAGS because `cargo doc --check` isn't yet implemented (https://github.com/rust-lang/cargo/issues/10025).
           RUSTDOCFLAGS: "-D warnings"

crates/ruff_python_formatter/src/comments/debug.rs

@@ -36,7 +36,7 @@ impl Debug for DebugComment<'_> {
     }
 }
 
-/// Pretty-printed debug representation of [`Comments`].
+/// Pretty-printed debug representation of [`Comments`](super::Comments).
 pub(crate) struct DebugComments<'a> {
     comments: &'a CommentsMap<'a>,
     source_code: SourceCode<'a>,

crates/ruff_python_formatter/src/comments/map.rs

@@ -504,7 +504,7 @@ impl InOrderEntry {
 
 #[derive(Clone, Debug)]
 struct OutOfOrderEntry {
-    /// Index into the [`MultiMap::out_of_order`] vector at which offset the leading vec is stored.
+    /// Index into the [`MultiMap::out_of_order_parts`] vector at which offset the leading vec is stored.
     leading_index: usize,
     _count: Count<OutOfOrderEntry>,
 }

crates/ruff_python_formatter/src/comments/node_key.rs

@@ -2,7 +2,8 @@ use ruff_python_ast::AnyNodeRef;
 use std::fmt::{Debug, Formatter};
 use std::hash::{Hash, Hasher};
 
-/// Used as key into the [`MultiMap`] storing the comments per node by [`Comments`].
+/// Used as key into the [`MultiMap`](super::MultiMap) storing the comments per node by
+/// [`Comments`](super::Comments).
 ///
 /// Implements equality and hashing based on the address of the [`AnyNodeRef`] to get fast and cheap
 /// hashing/equality comparison.

crates/ruff_python_formatter/src/comments/placement.rs

@@ -1974,8 +1974,8 @@ fn handle_unary_op_comment<'a>(
 /// )
 /// ```
 ///
-/// The comment will be attached to the [`Arguments`] node as a dangling comment, to ensure
+/// The comment will be attached to the [`Arguments`](ast::Arguments) node as a dangling comment, to
-/// that it remains on the same line as open parenthesis.
+/// ensure that it remains on the same line as open parenthesis.
 ///
 /// Similarly, given:
 /// ```python
@@ -1984,8 +1984,8 @@ fn handle_unary_op_comment<'a>(
 /// ] = ...
 /// ```
 ///
-/// The comment will be attached to the [`TypeParams`] node as a dangling comment, to ensure
+/// The comment will be attached to the [`TypeParams`](ast::TypeParams) node as a dangling comment,
-/// that it remains on the same line as open bracket.
+/// to ensure that it remains on the same line as open bracket.
 fn handle_bracketed_end_of_line_comment<'a>(
     comment: DecoratedComment<'a>,
     source: &str,

crates/ruff_python_formatter/src/comments/visitor.rs

@@ -174,7 +174,8 @@ impl<'ast> SourceOrderVisitor<'ast> for CommentsVisitor<'ast, '_> {
 
 /// A comment decorated with additional information about its surrounding context in the source document.
 ///
-/// Used by [`CommentStyle::place_comment`] to determine if this should become a [leading](self#leading-comments), [dangling](self#dangling-comments), or [trailing](self#trailing-comments) comment.
+/// Used by [`place_comment`] to determine if this should become a [leading](self#leading-comments),
+/// [dangling](self#dangling-comments), or [trailing](self#trailing-comments) comment.
 #[derive(Debug, Clone)]
 pub(crate) struct DecoratedComment<'a> {
     enclosing: AnyNodeRef<'a>,
@@ -465,7 +466,7 @@ pub(super) enum CommentPlacement<'a> {
     ///
     /// [`preceding_node`]: DecoratedComment::preceding_node
     /// [`following_node`]: DecoratedComment::following_node
-    /// [`enclosing_node`]: DecoratedComment::enclosing_node_id
+    /// [`enclosing_node`]: DecoratedComment::enclosing_node
     /// [trailing comment]: self#trailing-comments
     /// [leading comment]: self#leading-comments
     /// [dangling comment]: self#dangling-comments

crates/ruff_python_formatter/src/context.rs

@@ -166,7 +166,7 @@ impl InterpolatedStringState {
         }
     }
 
-    /// Returns `true` if the interpolated string state is [`NestedInterpolatedElement`].
+    /// Returns `true` if the interpolated string state is [`Self::NestedInterpolatedElement`].
     pub(crate) fn is_nested(self) -> bool {
         matches!(self, Self::NestedInterpolatedElement(..))
     }

crates/ruff_python_formatter/src/expression/binary_like.rs

@@ -1095,9 +1095,9 @@ impl OperandIndex {
         }
     }
 
-    /// Returns the index of the operand's right operator. The method always returns an index
+    /// Returns the index of the operand's right operator. The method always returns an index even
-    /// even if the operand has no right operator. Use [`BinaryCallChain::get_operator`] to test if
+    /// if the operand has no right operator. Use [`FlatBinaryExpressionSlice::get_operator`] to
-    /// the operand has a right operator.
+    /// test if the operand has a right operator.
     fn right_operator(self) -> OperatorIndex {
         OperatorIndex::new(self.0 + 1)
     }

crates/ruff_python_formatter/src/expression/parentheses.rs

@@ -56,18 +56,20 @@ pub(crate) enum Parenthesize {
     /// Adding parentheses is desired to prevent the comments from wandering.
     IfRequired,
 
-    /// Same as [`Self::IfBreaks`] except that it uses [`parenthesize_if_expands`] for expressions
+    /// Same as [`Self::IfBreaks`] except that it uses
-    /// with the layout [`NeedsParentheses::BestFit`] which is used by non-splittable
+    /// [`parenthesize_if_expands`](crate::builders::parenthesize_if_expands) for expressions with
-    /// expressions like literals, name, and strings.
+    /// the layout [`OptionalParentheses::BestFit`] which is used by non-splittable expressions like
+    /// literals, name, and strings.
     ///
     /// Use this layout over `IfBreaks` when there's a sequence of `maybe_parenthesize_expression`
     /// in a single logical-line and you want to break from right-to-left. Use `IfBreaks` for the
     /// first expression and `IfBreaksParenthesized` for the rest.
     IfBreaksParenthesized,
 
-    /// Same as [`Self::IfBreaksParenthesized`] but uses [`parenthesize_if_expands`] for nested
+    /// Same as [`Self::IfBreaksParenthesized`] but uses
-    /// [`maybe_parenthesized_expression`] calls unlike other layouts that always omit parentheses
+    /// [`parenthesize_if_expands`](crate::builders::parenthesize_if_expands) for nested
-    /// when outer parentheses are present.
+    /// [`maybe_parenthesized_expression`](crate::expression::maybe_parenthesize_expression) calls
+    /// unlike other layouts that always omit parentheses when outer parentheses are present.
     IfBreaksParenthesizedNested,
 }
 

crates/ruff_python_formatter/src/pattern/mod.rs

@@ -214,8 +214,9 @@ impl Format<PyFormatContext<'_>> for MaybeParenthesizePattern<'_> {
     }
 }
 
-/// This function is very similar to [`can_omit_optional_parentheses`] with the only difference that it is for patterns
+/// This function is very similar to
-/// and not expressions.
+/// [`can_omit_optional_parentheses`](crate::expression::can_omit_optional_parentheses)
+/// with the only difference that it is for patterns and not expressions.
 ///
 /// The base idea of the omit optional parentheses layout is to prefer using parentheses of sub-patterns
 /// when splitting the pattern over introducing new patterns. For example, prefer splitting the sequence pattern in

crates/ruff_python_formatter/src/pattern/pattern_arguments.rs

@@ -72,8 +72,9 @@ impl FormatNodeRule<PatternArguments> for FormatPatternArguments {
     }
 }
 
-/// Returns `true` if the pattern (which is the only argument to a [`PatternMatchClass`]) is
+/// Returns `true` if the pattern (which is the only argument to a
-/// parenthesized. Used to avoid falsely assuming that `x` is parenthesized in cases like:
+/// [`PatternMatchClass`](ruff_python_ast::PatternMatchClass)) is parenthesized.
+/// Used to avoid falsely assuming that `x` is parenthesized in cases like:
 /// ```python
 /// case Point2D(x): ...
 /// ```

crates/ruff_python_formatter/src/range.rs

@@ -23,7 +23,8 @@ use crate::{FormatModuleError, PyFormatOptions, format_module_source};
 ///
 /// The returned formatted range guarantees to cover at least `range` (excluding whitespace), but the range might be larger.
 /// Some cases in which the returned range is larger than `range` are:
-/// * The logical lines in `range` use a indentation different from the configured [`IndentStyle`] and [`IndentWidth`].
+/// * The logical lines in `range` use a indentation different from the configured [`IndentStyle`]
+///   and [`IndentWidth`](ruff_formatter::IndentWidth).
 /// * `range` is smaller than a logical lines and the formatter needs to format the entire logical line.
 /// * `range` falls on a single line body.
 ///
@@ -129,16 +130,19 @@ pub fn format_range(
 /// b) formatting a sub-expression has fewer split points than formatting the entire expressions.
 ///
 /// ### Possible docstrings
-/// Strings that are suspected to be docstrings are excluded from the search to format the enclosing suite instead
+/// Strings that are suspected to be docstrings are excluded from the search to format the enclosing
-/// so that the formatter's docstring detection in [`FormatSuite`] correctly detects and formats the docstrings.
+/// suite instead so that the formatter's docstring detection in
+/// [`FormatSuite`](crate::statement::suite::FormatSuite) correctly detects and formats the
+/// docstrings.
 ///
 /// ### Compound statements with a simple statement body
 /// Don't include simple-statement bodies of compound statements `if True: pass` because the formatter
-/// must run [`FormatClauseBody`] to determine if the body should be collapsed or not.
+/// must run `FormatClauseBody` to determine if the body should be collapsed or not.
 ///
 /// ### Incorrectly indented code
-/// Code that uses indentations that don't match the configured [`IndentStyle`] and [`IndentWidth`] are excluded from the search,
+/// Code that uses indentations that don't match the configured [`IndentStyle`] and
-/// because formatting such nodes on their own can lead to indentation mismatch with its sibling nodes.
+/// [`IndentWidth`](ruff_formatter::IndentWidth) are excluded from the search, because formatting
+/// such nodes on their own can lead to indentation mismatch with its sibling nodes.
 ///
 /// ## Suppression comments
 /// The search ends when `range` falls into a suppressed range because there's nothing to format. It also avoids that the
@@ -279,13 +283,15 @@ enum EnclosingNode<'a> {
 ///
 /// ## Compound statements with simple statement bodies
 /// Similar to [`find_enclosing_node`], exclude the compound statement's body if it is a simple statement (not a suite) from the search to format the entire clause header
-/// with the body. This ensures that the formatter runs [`FormatClauseBody`] that determines if the body should be indented.s
+/// with the body. This ensures that the formatter runs `FormatClauseBody` that determines if the body should be indented.
 ///
 /// ## Non-standard indentation
-/// Node's that use an indentation that doesn't match the configured [`IndentStyle`] and [`IndentWidth`] are excluded from the search.
+/// Nodes that use an indentation that doesn't match the configured [`IndentStyle`] and
-/// This is because the formatter always uses the configured [`IndentStyle`] and [`IndentWidth`], resulting in the
+/// [`IndentWidth`](ruff_formatter::IndentWidth) are excluded from the search. This is because the
-/// formatted nodes using a different indentation than the unformatted sibling nodes. This would be tolerable
+/// formatter always uses the configured [`IndentStyle`] and
-/// in non whitespace sensitive languages like JavaScript but results in lexical errors in Python.
+/// [`IndentWidth`](ruff_formatter::IndentWidth), resulting in the formatted nodes using a different
+/// indentation than the unformatted sibling nodes. This would be tolerable in non whitespace
+/// sensitive languages like JavaScript but results in lexical errors in Python.
 ///
 /// ## Implementation
 /// It would probably be possible to merge this visitor with [`FindEnclosingNode`] but they are separate because
@@ -713,9 +719,11 @@ impl Format<PyFormatContext<'_>> for FormatEnclosingNode<'_> {
     }
 }
 
-/// Computes the level of indentation for `indentation` when using the configured [`IndentStyle`] and [`IndentWidth`].
+/// Computes the level of indentation for `indentation` when using the configured [`IndentStyle`]
+/// and [`IndentWidth`](ruff_formatter::IndentWidth).
 ///
-/// Returns `None` if the indentation doesn't conform to the configured [`IndentStyle`] and [`IndentWidth`].
+/// Returns `None` if the indentation doesn't conform to the configured [`IndentStyle`] and
+/// [`IndentWidth`](ruff_formatter::IndentWidth).
 ///
 /// # Panics
 /// If `offset` is outside of `source`.

crates/ruff_python_formatter/src/statement/stmt_assign.rs

@@ -184,7 +184,7 @@ impl Format<PyFormatContext<'_>> for FormatTargetWithEqualOperator<'_> {
 /// No parentheses are added for `short` because it fits into the configured line length, regardless of whether
 /// the comment exceeds the line width or not.
 ///
-/// This logic isn't implemented in [`place_comment`] by associating trailing statement comments to the expression because
+/// This logic isn't implemented in `place_comment` by associating trailing statement comments to the expression because
 /// doing so breaks the suite empty lines formatting that relies on trailing comments to be stored on the statement.
 #[derive(Debug)]
 pub(super) enum FormatStatementsLastExpression<'a> {
@@ -202,8 +202,8 @@ pub(super) enum FormatStatementsLastExpression<'a> {
     /// ] = some_long_value
     /// ```
     ///
-    /// This layout is preferred over [`RightToLeft`] if the left is unsplittable (single keyword like `return` or a Name)
+    /// This layout is preferred over [`Self::RightToLeft`] if the left is unsplittable (single
-    /// because it has better performance characteristics.
+    /// keyword like `return` or a Name) because it has better performance characteristics.
     LeftToRight {
         /// The right side of an assignment or the value returned in a return statement.
         value: &'a Expr,
@@ -1083,11 +1083,10 @@ impl Format<PyFormatContext<'_>> for InterpolatedString<'_> {
 /// For legibility, we discuss only the case of f-strings below, but the
 /// same comments apply to t-strings.
 ///
-/// This is just a wrapper around [`FormatFString`] while considering a special
+/// This is just a wrapper around [`FormatFString`](crate::other::f_string::FormatFString) while
-/// case when the f-string is at an assignment statement's value position.
+/// considering a special case when the f-string is at an assignment statement's value position.
-/// This is necessary  to prevent an instability where an f-string contains a
+/// This is necessary to prevent an instability where an f-string contains a multiline expression
-/// multiline expression and the f-string fits on the line, but only when it's
+/// and the f-string fits on the line, but only when it's surrounded by parentheses.
-/// surrounded by parentheses.
 ///
 /// ```python
 /// aaaaaaaaaaaaaaaaaa = f"testeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee{

crates/ruff_python_formatter/src/statement/stmt_with.rs

@@ -177,8 +177,10 @@ enum WithItemsLayout<'a> {
     ///     ...
     /// ```
     ///
-    /// In this case, use [`maybe_parenthesize_expression`] to format the context expression
+    /// In this case, use
-    /// to get the exact same formatting as when formatting an expression in any other clause header.
+    /// [`maybe_parenthesize_expression`](crate::expression::maybe_parenthesize_expression) to
+    /// format the context expression to get the exact same formatting as when formatting an
+    /// expression in any other clause header.
     ///
     /// Only used for Python 3.9+
     ///

crates/ruff_python_formatter/src/string/docstring.rs

@@ -783,7 +783,7 @@ enum CodeExampleKind<'src> {
     ///
     /// Documentation describing doctests and how they're recognized can be
     /// found as part of the Python standard library:
-    /// https://docs.python.org/3/library/doctest.html.
+    /// <https://docs.python.org/3/library/doctest.html>.
     ///
     /// (You'll likely need to read the [regex matching] used internally by the
     /// doctest module to determine more precisely how it works.)

crates/ruff_python_formatter/src/string/normalize.rs

@@ -38,8 +38,9 @@ impl<'a, 'src> StringNormalizer<'a, 'src> {
     /// it can't because the string contains the preferred quotes OR
     /// it leads to more escaping.
     ///
-    /// Note: If you add more cases here where we return `QuoteStyle::Preserve`,
+    /// Note: If you add more cases here where we return `QuoteStyle::Preserve`, make sure to also
-    /// make sure to also add them to [`FormatImplicitConcatenatedStringFlat::new`].
+    /// add them to
+    /// [`FormatImplicitConcatenatedStringFlat::new`](crate::string::implicit::FormatImplicitConcatenatedStringFlat::new).
     pub(super) fn preferred_quote_style(&self, string: StringLikePart) -> QuoteStyle {
         let preferred_quote_style = self
             .preferred_quote_style

crates/ruff_python_formatter/src/type_param/type_params.rs

@@ -9,7 +9,7 @@ use crate::prelude::*;
 #[derive(Default)]
 pub struct FormatTypeParams;
 
-/// Formats a sequence of [`TypeParam`] nodes.
+/// Formats a sequence of [`TypeParam`](ruff_python_ast::TypeParam) nodes.
 impl FormatNodeRule<TypeParams> for FormatTypeParams {
     fn fmt_fields(&self, item: &TypeParams, f: &mut PyFormatter) -> FormatResult<()> {
         // A dangling comment indicates a comment on the same line as the opening bracket, e.g.:

crates/ruff_python_formatter/src/verbatim.rs

@@ -679,8 +679,9 @@ impl Indentation {
 
 /// Returns `true` for a space or tab character.
 ///
-/// This is different than [`is_python_whitespace`] in that it returns `false` for a form feed character.
+/// This is different than [`is_python_whitespace`](ruff_python_trivia::is_python_whitespace) in
-/// Form feed characters are excluded because they should be preserved in the suppressed output.
+/// that it returns `false` for a form feed character. Form feed characters are excluded because
+/// they should be preserved in the suppressed output.
 const fn is_indent_whitespace(c: char) -> bool {
     matches!(c, ' ' | '\t')
 }