docs: all `flake8-comprehension` rules (#3631)

crates/ruff/src/rules/flake8_comprehensions/rules/unnecessary_collection_call.rs

@@ -12,6 +12,30 @@ use crate::rules::flake8_comprehensions::settings::Settings;
 
 use super::helpers;
 
+/// ## What it does
+/// Checks for unnecessary `dict`, `list` or `tuple` calls that can be
+/// rewritten as empty literals.
+///
+/// ## Why is this bad?
+/// It's unnecessary to call e.g., `dict()` as opposed to using an empty
+/// literal (`{}`). The former is slower because the name `dict` must be
+/// looked up in the global scope in case it has been rebound.
+///
+/// ## Examples
+/// ```python
+/// dict()
+/// dict(a=1, b=2)
+/// list()
+/// tuple()
+/// ```
+///
+/// Use instead:
+/// ```python
+/// {}
+/// {"a": 1, "b": 2}
+/// []
+/// ()
+/// ```
 #[violation]
 pub struct UnnecessaryCollectionCall {
     pub obj_type: String,

crates/ruff/src/rules/flake8_comprehensions/rules/unnecessary_double_cast_or_process.rs

@@ -31,6 +31,7 @@ use super::helpers;
 ///
 /// This rule applies to a variety of functions, including `list`, `reversed`,
 /// `set`, `sorted`, and `tuple`. For example:
+///
 /// - Instead of `list(list(iterable))`, use `list(iterable)`.
 /// - Instead of `list(tuple(iterable))`, use `list(iterable)`.
 /// - Instead of `tuple(list(iterable))`, use `tuple(iterable)`.

crates/ruff/src/rules/flake8_comprehensions/rules/unnecessary_list_call.rs

@@ -11,6 +11,21 @@ use crate::rules::flake8_comprehensions::fixes;
 
 use super::helpers;
 
+/// ## What it does
+/// Checks for unnecessary `list` calls around list comprehensions.
+///
+/// ## Why is it bad?
+/// It is redundant to use a `list` call around a list comprehension.
+///
+/// ## Examples
+/// ```python
+/// list([f(x) for x in foo])
+/// ```
+///
+/// Use instead
+/// ```python
+/// [f(x) for x in foo]
+/// ```
 #[violation]
 pub struct UnnecessaryListCall;
 

crates/ruff/src/rules/flake8_comprehensions/rules/unnecessary_list_comprehension_dict.rs

@@ -11,6 +11,22 @@ use crate::rules::flake8_comprehensions::fixes;
 
 use super::helpers;
 
+/// ## What it does
+/// Checks for unnecessary list comprehensions.
+///
+/// ## Why is it bad?
+/// It's unnecessary to use a list comprehension inside a call to `dict`,
+/// since there is an equivalent comprehension for this type.
+///
+/// ## Examples
+/// ```python
+/// dict([(x, f(x)) for x in foo])
+/// ```
+///
+/// Use instead:
+/// ```python
+/// {x: f(x) for x in foo}
+/// ```
 #[violation]
 pub struct UnnecessaryListComprehensionDict;
 

crates/ruff/src/rules/flake8_comprehensions/rules/unnecessary_list_comprehension_set.rs

@@ -11,6 +11,22 @@ use crate::rules::flake8_comprehensions::fixes;
 
 use super::helpers;
 
+/// ## What it does
+/// Checks for unnecessary list comprehensions.
+///
+/// ## Why is it bad?
+/// It's unnecessary to use a list comprehension inside a call to `set`,
+/// since there is an equivalent comprehension for this type.
+///
+/// ## Examples
+/// ```python
+/// set([f(x) for x in foo])
+/// ```
+///
+/// Use instead:
+/// ```python
+/// {f(x) for x in foo}
+/// ```
 #[violation]
 pub struct UnnecessaryListComprehensionSet;
 

crates/ruff/src/rules/flake8_comprehensions/rules/unnecessary_literal_dict.rs

@@ -11,6 +11,26 @@ use crate::rules::flake8_comprehensions::fixes;
 
 use super::helpers;
 
+/// ## What it does
+/// Checks for unnecessary `list` or `tuple` literals.
+///
+/// ## Why is it bad?
+/// It's unnecessary to use a list or tuple literal within a call to `dict`.
+/// It can be rewritten as a dict literal (`{}`).
+///
+/// ## Examples
+/// ```python
+/// dict([(1, 2), (3, 4)])
+/// dict(((1, 2), (3, 4)))
+/// dict([])
+/// ```
+///
+/// Use instead:
+/// ```python
+/// {1: 2, 3: 4}
+/// {1: 2, 3: 4}
+/// {}
+/// ```
 #[violation]
 pub struct UnnecessaryLiteralDict {
     pub obj_type: String,

crates/ruff/src/rules/flake8_comprehensions/rules/unnecessary_literal_set.rs

@@ -11,6 +11,27 @@ use crate::rules::flake8_comprehensions::fixes;
 
 use super::helpers;
 
+/// ## What it does
+/// Checks for `set` calls that take unnecessary `list` or `tuple` literals
+/// as arguments.
+///
+/// ## Why is it bad?
+/// It's unnecessary to use a list or tuple literal within a call to `set`.
+/// Instead, the expression can be rewritten as a set literal.
+///
+/// ## Examples
+/// ```python
+/// set([1, 2])
+/// set((1, 2))
+/// set([])
+/// ```
+///
+/// Use instead:
+/// ```python
+/// {1, 2}
+/// {1, 2}
+/// set()
+/// ```
 #[violation]
 pub struct UnnecessaryLiteralSet {
     pub obj_type: String,

crates/ruff/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_list_call.rs

@@ -11,6 +11,29 @@ use crate::rules::flake8_comprehensions::fixes;
 
 use super::helpers;
 
+/// ## What it does
+/// Checks for `list` calls that take unnecessary list or tuple literals as
+/// arguments.
+///
+/// ## Why is it bad?
+/// It's unnecessary to use a list or tuple literal within a `list()` call,
+/// since there is a literal syntax for these types.
+///
+/// If a list literal is passed in, then the outer call to `list()` should be
+/// removed. Otherwise, if a tuple literal is passed in, then it should be
+/// rewritten as a `list` literal.
+///
+/// ## Examples
+/// ```python
+/// list([1, 2])
+/// list((1, 2))
+/// ```
+///
+/// Use instead:
+/// ```python
+/// [1, 2]
+/// [1, 2]
+/// ```
 #[violation]
 pub struct UnnecessaryLiteralWithinListCall {
     pub literal: String,

crates/ruff/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_tuple_call.rs

@@ -11,6 +11,29 @@ use crate::rules::flake8_comprehensions::fixes;
 
 use super::helpers;
 
+/// ## What it does
+/// Checks for `tuple` calls that take unnecessary list or tuple literals as
+/// arguments.
+///
+/// ## Why is it bad?
+/// It's unnecessary to use a list or tuple literal within a `tuple()` call,
+/// since there is a literal syntax for these types.
+///
+/// If a list literal was passed, then it should be rewritten as a `tuple`
+/// literal. Otherwise, if a tuple literal was passed, then the outer call
+/// to `list()` should be removed.
+///
+/// ## Examples
+/// ```python
+/// tuple([1, 2])
+/// tuple((1, 2))
+/// ```
+///
+/// Use instead:
+/// ```python
+/// (1, 2)
+/// (1, 2)
+/// ```
 #[violation]
 pub struct UnnecessaryLiteralWithinTupleCall {
     pub literal: String,

crates/ruff/src/rules/flake8_comprehensions/rules/unnecessary_map.rs

@@ -32,6 +32,7 @@ use super::helpers;
 ///
 /// This rule also applies to `map` calls within `list`, `set`, and `dict`
 /// calls. For example:
+///
 /// - Instead of `list(map(lambda num: num * 2, nums))`, use
 ///   `[num * 2 for num in nums]`.
 /// - Instead of `set(map(lambda num: num % 2 == 0, nums))`, use

crates/ruff/src/rules/flake8_comprehensions/rules/unnecessary_subscript_reversal.rs

@@ -9,6 +9,27 @@ use crate::checkers::ast::Checker;
 
 use super::helpers;
 
+/// ## What it does
+/// Checks for unnecessary subscript reversal of iterable.
+///
+/// ## Why is it bad?
+/// It's unnecessary to reverse the order of an iterable when passing it
+/// into `reversed()`, `set()` or `sorted()` functions as they will change
+/// the order of the elements again.
+///
+/// ## Examples
+/// ```python
+/// reversed(iterable[::-1])
+/// set(iterable[::-1])
+/// sorted(iterable)[::-1]
+/// ```
+///
+/// Use instead:
+/// ```python
+/// reversed(iterable)
+/// set(iterable)
+/// sorted(iterable, reverse=True)
+/// ```
 #[violation]
 pub struct UnnecessarySubscriptReversal {
     pub func: String,