diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 993ecfac97..b218a2e99b 100644 --- a/.github/workflows/ci.yaml +++ b/.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" diff --git a/crates/ruff_python_formatter/src/comments/debug.rs b/crates/ruff_python_formatter/src/comments/debug.rs index 3e4ae7c6bd..0adbba24f3 100644 --- a/crates/ruff_python_formatter/src/comments/debug.rs +++ b/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>, diff --git a/crates/ruff_python_formatter/src/comments/map.rs b/crates/ruff_python_formatter/src/comments/map.rs index 3f6d621a59..8d25f4f8a7 100644 --- a/crates/ruff_python_formatter/src/comments/map.rs +++ b/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, } diff --git a/crates/ruff_python_formatter/src/comments/node_key.rs b/crates/ruff_python_formatter/src/comments/node_key.rs index ec15ced488..22f4582132 100644 --- a/crates/ruff_python_formatter/src/comments/node_key.rs +++ b/crates/ruff_python_formatter/src/comments/node_key.rs @@ -2,7 +2,7 @@ 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. diff --git a/crates/ruff_python_formatter/src/comments/placement.rs b/crates/ruff_python_formatter/src/comments/placement.rs index 76449285be..c9b71d0f21 100644 --- a/crates/ruff_python_formatter/src/comments/placement.rs +++ b/crates/ruff_python_formatter/src/comments/placement.rs @@ -1974,7 +1974,7 @@ 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 ensure /// that it remains on the same line as open parenthesis. /// /// Similarly, given: @@ -1984,7 +1984,7 @@ 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, to ensure /// that it remains on the same line as open bracket. fn handle_bracketed_end_of_line_comment<'a>( comment: DecoratedComment<'a>, diff --git a/crates/ruff_python_formatter/src/comments/visitor.rs b/crates/ruff_python_formatter/src/comments/visitor.rs index b9670a3ee8..786fa7a574 100644 --- a/crates/ruff_python_formatter/src/comments/visitor.rs +++ b/crates/ruff_python_formatter/src/comments/visitor.rs @@ -174,7 +174,7 @@ 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 +465,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 diff --git a/crates/ruff_python_formatter/src/context.rs b/crates/ruff_python_formatter/src/context.rs index 239edc8d5b..8eaf52ee35 100644 --- a/crates/ruff_python_formatter/src/context.rs +++ b/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(..)) } diff --git a/crates/ruff_python_formatter/src/expression/binary_like.rs b/crates/ruff_python_formatter/src/expression/binary_like.rs index 5d86608452..7363e67cd0 100644 --- a/crates/ruff_python_formatter/src/expression/binary_like.rs +++ b/crates/ruff_python_formatter/src/expression/binary_like.rs @@ -1096,7 +1096,7 @@ impl OperandIndex { } /// Returns the index of the operand's right operator. The method always returns an index - /// even if the operand has no right operator. Use [`BinaryCallChain::get_operator`] to test if + /// even if the operand has no right operator. Use [`FlatBinaryExpressionSlice::get_operator`] to test if /// the operand has a right operator. fn right_operator(self) -> OperatorIndex { OperatorIndex::new(self.0 + 1) diff --git a/crates/ruff_python_formatter/src/expression/parentheses.rs b/crates/ruff_python_formatter/src/expression/parentheses.rs index a76f8a0aec..c3ee1c7ee7 100644 --- a/crates/ruff_python_formatter/src/expression/parentheses.rs +++ b/crates/ruff_python_formatter/src/expression/parentheses.rs @@ -56,8 +56,8 @@ 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 - /// with the layout [`NeedsParentheses::BestFit`] which is used by non-splittable + /// Same as [`Self::IfBreaks`] except that it uses [`parenthesize_if_expands`](crate::builders::parenthesize_if_expands) for expressions + /// with 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` @@ -65,8 +65,8 @@ pub(crate) enum Parenthesize { /// first expression and `IfBreaksParenthesized` for the rest. IfBreaksParenthesized, - /// Same as [`Self::IfBreaksParenthesized`] but uses [`parenthesize_if_expands`] for nested - /// [`maybe_parenthesized_expression`] calls unlike other layouts that always omit parentheses + /// Same as [`Self::IfBreaksParenthesized`] but uses [`parenthesize_if_expands`](crate::builders::parenthesize_if_expands) for nested + /// [`maybe_parenthesized_expression`](crate::expression::maybe_parenthesize_expression) calls unlike other layouts that always omit parentheses /// when outer parentheses are present. IfBreaksParenthesizedNested, } diff --git a/crates/ruff_python_formatter/src/pattern/mod.rs b/crates/ruff_python_formatter/src/pattern/mod.rs index a379aeb849..dc188095ef 100644 --- a/crates/ruff_python_formatter/src/pattern/mod.rs +++ b/crates/ruff_python_formatter/src/pattern/mod.rs @@ -214,7 +214,7 @@ impl Format> 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 [`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 diff --git a/crates/ruff_python_formatter/src/pattern/pattern_arguments.rs b/crates/ruff_python_formatter/src/pattern/pattern_arguments.rs index 94d7448226..fb3382e7d9 100644 --- a/crates/ruff_python_formatter/src/pattern/pattern_arguments.rs +++ b/crates/ruff_python_formatter/src/pattern/pattern_arguments.rs @@ -72,7 +72,7 @@ impl FormatNodeRule 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 [`PatternMatchClass`](ruff_python_ast::PatternMatchClass)) is /// parenthesized. Used to avoid falsely assuming that `x` is parenthesized in cases like: /// ```python /// case Point2D(x): ... diff --git a/crates/ruff_python_formatter/src/range.rs b/crates/ruff_python_formatter/src/range.rs index 436c1a12c2..be63c69c78 100644 --- a/crates/ruff_python_formatter/src/range.rs +++ b/crates/ruff_python_formatter/src/range.rs @@ -23,7 +23,7 @@ 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. /// @@ -130,14 +130,14 @@ pub fn format_range( /// /// ### Possible docstrings /// Strings that are suspected to be docstrings are excluded from the search to format the enclosing suite instead -/// so that the formatter's docstring detection in [`FormatSuite`] correctly detects and formats the docstrings. +/// 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 [`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 @@ -279,11 +279,11 @@ 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. -/// This is because the formatter always uses the configured [`IndentStyle`] and [`IndentWidth`], resulting in the +/// Node's that use an indentation that doesn't match the configured [`IndentStyle`] and [`IndentWidth`](ruff_formatter::IndentWidth) are excluded from the search. +/// This is because the formatter always uses the configured [`IndentStyle`] and [`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. /// @@ -713,9 +713,9 @@ impl Format> 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`. diff --git a/crates/ruff_python_formatter/src/statement/stmt_assign.rs b/crates/ruff_python_formatter/src/statement/stmt_assign.rs index b9fbe6b7a3..f213654010 100644 --- a/crates/ruff_python_formatter/src/statement/stmt_assign.rs +++ b/crates/ruff_python_formatter/src/statement/stmt_assign.rs @@ -184,7 +184,7 @@ impl Format> 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,7 +202,7 @@ 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 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. @@ -1083,7 +1083,7 @@ impl Format> 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 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 /// multiline expression and the f-string fits on the line, but only when it's diff --git a/crates/ruff_python_formatter/src/statement/stmt_with.rs b/crates/ruff_python_formatter/src/statement/stmt_with.rs index 3ef8e52a23..5cfe7952a5 100644 --- a/crates/ruff_python_formatter/src/statement/stmt_with.rs +++ b/crates/ruff_python_formatter/src/statement/stmt_with.rs @@ -177,7 +177,7 @@ enum WithItemsLayout<'a> { /// ... /// ``` /// - /// In this case, use [`maybe_parenthesize_expression`] to format the context expression + /// In this case, use [`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+ diff --git a/crates/ruff_python_formatter/src/string/docstring.rs b/crates/ruff_python_formatter/src/string/docstring.rs index ad357fc65e..c4554175d5 100644 --- a/crates/ruff_python_formatter/src/string/docstring.rs +++ b/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. + /// . /// /// (You'll likely need to read the [regex matching] used internally by the /// doctest module to determine more precisely how it works.) diff --git a/crates/ruff_python_formatter/src/string/normalize.rs b/crates/ruff_python_formatter/src/string/normalize.rs index fabd10a029..2ed4acb0f1 100644 --- a/crates/ruff_python_formatter/src/string/normalize.rs +++ b/crates/ruff_python_formatter/src/string/normalize.rs @@ -39,7 +39,7 @@ impl<'a, 'src> StringNormalizer<'a, 'src> { /// it leads to more escaping. /// /// Note: If you add more cases here where we return `QuoteStyle::Preserve`, - /// make sure to also add them to [`FormatImplicitConcatenatedStringFlat::new`]. + /// make sure to also 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 diff --git a/crates/ruff_python_formatter/src/type_param/type_params.rs b/crates/ruff_python_formatter/src/type_param/type_params.rs index e243dc6006..50c2cc5770 100644 --- a/crates/ruff_python_formatter/src/type_param/type_params.rs +++ b/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 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.: diff --git a/crates/ruff_python_formatter/src/verbatim.rs b/crates/ruff_python_formatter/src/verbatim.rs index e0bbf00ad6..751b74b174 100644 --- a/crates/ruff_python_formatter/src/verbatim.rs +++ b/crates/ruff_python_formatter/src/verbatim.rs @@ -679,7 +679,7 @@ 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 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')