Document `pub` items in multiple `clippy_utils` modules #15855

SignalWalker · 2025-10-09T19:01:58Z

Partially addressing #15569, document items in clippy_utils::{consts, higher, macros, paths, res, source, str_utils, sugg, usage, visitors}. The specific items documented are listed in each commit description, along with notes.

This is my first time contributing to any official Rust internals/tools, so please let me know if I misunderstood anything. (I'm not really sure that "refers" is the right verb for the relationship between a Place and a HIR node, for example.)

As I understand it, this is considered purely an internal change, so:
changelog: none

rustbot · 2025-10-09T19:02:02Z

r? @llogiq

rustbot has assigned @llogiq.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

clippy_utils/src/consts.rs

SignalWalker · 2025-10-12T17:02:59Z

clippy_utils/src/consts.rs

        }
    }

+    /// Recursively consume [`Constant::Ref`] and return the innermost value.


I don't think "Recursively" is technically the right word, but I couldn't think of anything better that would still be succinct.

How about "removing all references to return the contained expression, e.g. &&T → T"?

clippy_utils/src/consts.rs

SignalWalker · 2025-10-12T17:04:25Z

clippy_utils/src/consts.rs

        }
    }

+    /// Attempts to evaluate the given [pattern expression](PatExpr) as a [`Constant`].


Not entirely sure this is accurate?

Why? I think it is.

I honestly don't remember. I think it was because the name of the function doesn't seem to imply that it has anything to do with constants?

SignalWalker · 2025-10-12T17:05:03Z

clippy_utils/src/consts.rs

+/// - If `val` is a [`ConstValue::Indirect`] and `ty` is an [`Array`](ty::Array) of
+///   [`Float`](ty::Float), returns a [`Constant::Vec`]
+///
+/// Otherwise, returns `None`.


Is this function actually as particular as described or am I missing something

I think you missed the Bool and RawPtr cases.

SignalWalker · 2025-10-12T17:06:03Z

clippy_utils/src/higher.rs

    pub body: &'hir Expr<'hir>,
    /// Span of the loop header
    pub span: Span,
+    /// The loop's label, if present


Link to https://doc.rust-lang.org/nightly/reference/expressions/loop-expr.html?highlight=label#loop-labels ?

SignalWalker · 2025-10-12T17:06:16Z

clippy_utils/src/higher.rs

    pub let_expr: &'hir Expr<'hir>,
    /// `while let` loop body
    pub if_then: &'hir Expr<'hir>,
+    /// The loop's label, if present


Link to https://doc.rust-lang.org/nightly/reference/expressions/loop-expr.html?highlight=label#loop-labels ?

SignalWalker · 2025-10-12T17:06:43Z

clippy_utils/src/macros.rs

    matches!(name, sym::assert_macro | sym::debug_assert_macro)
 }

+/// A `panic!()` expression, which may contain arguments


not sure about this one

Expn stands for expansion here, not expression. So it refers to the expansion of the panic! macro.

SignalWalker · 2025-10-12T17:07:15Z

clippy_utils/src/res.rs

@@ -1,3 +1,5 @@
+//! Utilities for node resolution.


Not sure if this fully describes this module?

SignalWalker · 2025-10-12T17:07:48Z

clippy_utils/src/source.rs


 /// Conversion of a value into the range portion of a `Span`.
 pub trait SpanRange: Sized {
+    /// Converts `self` into the range portion of a [`Span`].


not sure about this one

SignalWalker · 2025-10-12T17:08:07Z

clippy_utils/src/source.rs

    }
 }

+/// Extensions to [`SpanRange`].


could probably be more descriptive

SignalWalker · 2025-10-12T17:08:33Z

clippy_utils/src/source.rs

+/// Checks whether the code snippet referred to by the given [`Span`] is present in the source code.
+///
+/// For example, if the span refers to an attribute inserted during macro expansion, this will
+/// return false.


Not sure this is accurate

SignalWalker · 2025-10-12T17:08:54Z

clippy_utils/src/source.rs

 }

+/// Same as [`snippet_block_with_applicability()`], but first walks the span up to the given context
+/// using [`snippet_with_context()`].


Should this be more descriptive?

Yes, please. I for one wouldn't understand what this does without following the link.

SignalWalker · 2025-10-12T17:09:50Z

clippy_utils/src/str_utils.rs

+//! Utilities for analyzing and transforming strings.
+
 /// Dealing with string indices can be hard, this struct ensures that both the
 /// character and byte index are provided for correct indexing.


Should this mention that char_index and byte_index aren't guaranteed to agree with each other?

Yes. I keep remembering it because it's bitten me a few times, but it's always good to have a reminder nevertheless.

SignalWalker · 2025-10-12T17:10:12Z

clippy_utils/src/str_utils.rs

 }

 /// Dealing with string comparison can be complicated, this struct ensures that both the
 /// character and byte count are provided for correct indexing.


Should this mention that char_count and byte_count aren't guaranteed to agree with each other?

If we already have a note at the beginning of the file, that shouldn't be necessary.

It might be nice to have it in the docs for the structs, since it'll show up in, for example, IDE hints.

SignalWalker · 2025-10-12T17:10:46Z

clippy_utils/src/sugg.rs

        }
    }

+    /// Convert this suggestion into a [`String`] to be displayed to the user.


I'm assuming that this is this function's purpose based on how it's used elsewhere.

s/Convert/Format/, otherwise I agree.

SignalWalker · 2025-10-12T17:11:10Z

clippy_utils/src/usage.rs

@@ -1,3 +1,5 @@
+//! Contains utility functions for checking expression usage.


not sure about this one

It's more about variable usage, IIRC.

SignalWalker · 2025-10-12T17:11:42Z

clippy_utils/src/usage.rs

    mutated_variables(expr, cx).is_none_or(|mutated| mutated.contains(&variable))
 }

+/// Checks whether it is possible that the given [Place] refers to the given local.


"refers to"?

SignalWalker · 2025-10-12T17:12:16Z

clippy_utils/src/usage.rs

    .is_some()
 }

+/// Checks whether the given expression contains `return`, `break`, `continue`, or a macro call.


Describe why it checks for macro calls?

Probably because of panic! et al.

llogiq

Looks mostly good. I left a few suggestions.

View changes since this review

clippy_utils/src/consts.rs

llogiq · 2025-10-22T16:38:21Z

clippy_utils/src/consts.rs

        }
    }

+    /// Recursively consume [`Constant::Ref`] and return the innermost value.


How about "removing all references to return the contained expression, e.g. &&T → T"?

clippy_utils/src/consts.rs

llogiq · 2025-10-22T16:46:52Z

clippy_utils/src/consts.rs

        }
    }

+    /// Attempts to evaluate the given [pattern expression](PatExpr) as a [`Constant`].


Why? I think it is.

llogiq · 2025-10-22T16:48:36Z

clippy_utils/src/consts.rs

+/// - If `val` is a [`ConstValue::Indirect`] and `ty` is an [`Array`](ty::Array) of
+///   [`Float`](ty::Float), returns a [`Constant::Vec`]
+///
+/// Otherwise, returns `None`.


I think you missed the Bool and RawPtr cases.

llogiq · 2025-10-22T19:43:17Z

clippy_utils/src/str_utils.rs

 }

 /// Dealing with string comparison can be complicated, this struct ensures that both the
 /// character and byte count are provided for correct indexing.


If we already have a note at the beginning of the file, that shouldn't be necessary.

llogiq · 2025-10-22T19:44:03Z

clippy_utils/src/sugg.rs

        }
    }

+    /// Convert this suggestion into a [`String`] to be displayed to the user.


s/Convert/Format/, otherwise I agree.

llogiq · 2025-10-23T16:39:40Z

clippy_utils/src/usage.rs

    .is_some()
 }

+/// Checks whether the given expression contains `return`, `break`, `continue`, or a macro call.


Probably because of panic! et al.

llogiq · 2025-10-28T16:30:25Z

clippy_utils/src/usage.rs

@@ -1,3 +1,5 @@
+//! Contains utility functions for checking expression usage.


It's more about variable usage, IIRC.

clippy_utils/src/visitors.rs

llogiq · 2025-11-14T12:15:34Z

Ping? Are you still working on this?

@rustbot author

rustbot · 2025-11-14T12:15:38Z

Reminder, once the PR becomes ready for a review, use @rustbot ready.

- `is_potentially_mutated()` - `is_potentially_local_place()` - `ParamBindingIdCollector` - `BindingUsageFinder` - `contains_return_break_continue_macro()` - `local_used_in()` - `local_used_after_expr()`

- `IfLetOrMatch::scrutinee()` - `While.label` - `WhileLet.label`

- module - `MacroCall::is_local()` - `PanicExpn` - `PanicExpn::parse()` - `HirNode::hir_id()` - `HirNode::span()`

I'm not really sure how to document the `PathLookup` statics, so I'm skipping those for now.

- module - `HasHirId::hir_id()` - `MaybeTypeckRes` - `MaybeDef::opt_def_id()`

- `HasSession` - `HasSession::sess()` - `SpanRange::into_range()` - `IntoSpan::into_span()` - `IntoSpan::with_ctxt()` - `SpanRangeExt` - May want to be more specific with this one. - `SourceFileRange` and its fields - `is_present_in_source()` - This one feels a bit clunky to me; might want to rephrase. - `snippet_block_with_context()`

- module - fields of `StrIndex` - `StrIndex::new()` - fields of `StrCount` - `StrCount::new()` `StrIndex` and `StrCount` don't seem to guarantee that their fields are internally consistent; should this be documented?

- `Sugg::into_string()` I'm not sure that this is correct, but it does seem to be how its used elsewhere.

- module - `Descend::{Yes, No}` - `find_all_ret_expressions()` - `for_each_unconsumed_temporary()` - this one was mostly just reformatting the non-doc comment that was already there - `any_temporaries_need_ordered_drop()` - `contains_break_or_continue()`

- `Constant::Adt` - `Constant::partial_cmp()` - `Constant::peel_refs()` - `Constant::new_numeric_min()` - `Constant::new_numeric_max()` - `Constant::is_numeric_min()` - `Constant::is_numeric_max()` - `Constant::is_pos_infinity()` - `Constant::is_neg_infinity()` - `ConstantSource::is_local()` - `FullInt` and its variants - `ConstEvalCtxt::eval_pat_expr()` - `mir_to_const()`

rustbot · 2025-11-18T17:48:16Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

SignalWalker · 2025-11-18T17:50:16Z

Ping? Are you still working on this?

@rustbot author

Woops, sorry, thanks for pinging me.

Co-authored-by: llogiq <bogusandre@gmail.com>

- Clarify: - `consts::peel_refs()` - `consts::mir_to_const()` - `source::snippet_block_with_context()` - `str_utils::StrIndex` - `str_utils::StrCount` - `sugg::Sugg::into_string()` - `usage` - `usage::contains_return_break_continue_macro()` - Fix: - `macros::PanicExpn`

SignalWalker · 2025-11-18T19:15:32Z

Applied your suggestions; thanks!

@rustbot ready

rustbot assigned llogiq Oct 9, 2025

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties label Oct 9, 2025

SignalWalker force-pushed the master branch from baf163d to 3f700d2 Compare October 12, 2025 15:45

This comment has been minimized.

Sign in to view

SignalWalker changed the title ~~Document pub items in clippy_utils::usage~~ Document pub items in multiple clippy_utils modules Oct 12, 2025