Document fix safety for flake8-comprehensions and some pyupgrade rules (#8918)

See: https://github.com/astral-sh/ruff/issues/7993.

crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_call_around_sorted.rs

@@ -30,6 +30,14 @@ use crate::rules::flake8_comprehensions::fixes;
 /// ```python
 /// sorted(iterable, reverse=True)
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as `reversed` and `reverse=True` will
+/// yield different results in the event of custom sort keys or equality
+/// functions. Specifically, `reversed` will reverse the order of the
+/// collection, while `sorted` with `reverse=True` will perform a stable
+/// reverse sort, which will preserve the order of elements that compare as
+/// equal.
 #[violation]
 pub struct UnnecessaryCallAroundSorted {
     func: String,

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

@@ -32,6 +32,10 @@ use crate::rules::flake8_comprehensions::settings::Settings;
 /// []
 /// ()
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryCollectionCall {
     obj_type: String,

crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_comprehension.rs

@@ -29,6 +29,11 @@ use crate::rules::flake8_comprehensions::fixes;
 /// list(iterable)
 /// set(iterable)
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the comprehension. In most cases, though, comments will be
+/// preserved.
 #[violation]
 pub struct UnnecessaryComprehension {
     obj_type: String,

crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_comprehension_any_all.rs

@@ -40,6 +40,11 @@ use crate::rules::flake8_comprehensions::fixes;
 /// any(x.id for x in bar)
 /// all(x.id for x in bar)
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the comprehension. In most cases, though, comments will be
+/// preserved.
 #[violation]
 pub struct UnnecessaryComprehensionAnyAll;
 

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

@@ -43,6 +43,10 @@ use crate::rules::flake8_comprehensions::fixes;
 /// - Instead of `sorted(tuple(iterable))`, use `sorted(iterable)`.
 /// - Instead of `sorted(sorted(iterable))`, use `sorted(iterable)`.
 /// - Instead of `sorted(reversed(iterable))`, use `sorted(iterable)`.
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryDoubleCastOrProcess {
     inner: String,

crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_dict.rs

@@ -27,6 +27,10 @@ use super::helpers;
 /// ```python
 /// {x: f(x) for x in foo}
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryGeneratorDict;
 

crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_list.rs

@@ -28,6 +28,10 @@ use super::helpers;
 /// ```python
 /// [f(x) for x in foo]
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryGeneratorList;
 

crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_generator_set.rs

@@ -28,6 +28,10 @@ use super::helpers;
 /// ```python
 /// {f(x) for x in foo}
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryGeneratorSet;
 

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

@@ -25,6 +25,10 @@ use super::helpers;
 /// ```python
 /// [f(x) for x in foo]
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryListCall;
 

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

@@ -25,6 +25,10 @@ use super::helpers;
 /// ```python
 /// {x: f(x) for x in foo}
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryListComprehensionDict;
 

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

@@ -26,6 +26,10 @@ use super::helpers;
 /// ```python
 /// {f(x) for x in foo}
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryListComprehensionSet;
 

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

@@ -29,6 +29,10 @@ use super::helpers;
 /// {1: 2, 3: 4}
 /// {}
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryLiteralDict {
     obj_type: String,

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

@@ -31,6 +31,10 @@ use super::helpers;
 /// {1, 2}
 /// set()
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryLiteralSet {
     obj_type: String,

crates/ruff_linter/src/rules/flake8_comprehensions/rules/unnecessary_literal_within_dict_call.rs

@@ -46,6 +46,10 @@ impl fmt::Display for DictKind {
 /// {}
 /// {"a": 1}
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryLiteralWithinDictCall {
     kind: DictKind,

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

@@ -32,6 +32,10 @@ use super::helpers;
 /// [1, 2]
 /// [1, 2]
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryLiteralWithinListCall {
     literal: String,

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

@@ -33,6 +33,10 @@ use super::helpers;
 /// (1, 2)
 /// (1, 2)
 /// ```
+///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryLiteralWithinTupleCall {
     literal: String,

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

@@ -22,6 +22,16 @@ use super::helpers;
 /// using a generator expression or a comprehension, as the latter approach
 /// avoids the function call overhead, in addition to being more readable.
 ///
+/// 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
+///   `{num % 2 == 0 for num in nums}`.
+/// - Instead of `dict(map(lambda v: (v, v ** 2), values))`, use
+///   `{v: v ** 2 for v in values}`.
+///
 /// ## Examples
 /// ```python
 /// map(lambda x: x + 1, iterable)
@@ -32,15 +42,9 @@ use super::helpers;
 /// (x + 1 for x in iterable)
 /// ```
 ///
-/// 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
-///   `{num % 2 == 0 for num in nums}`.
-/// - Instead of `dict(map(lambda v: (v, v ** 2), values))`, use
-///   `{v: v ** 2 for v in values}`.
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may occasionally drop comments
+/// when rewriting the call. In most cases, though, comments will be preserved.
 #[violation]
 pub struct UnnecessaryMap {
     object_type: ObjectType,

crates/ruff_linter/src/rules/pyupgrade/rules/use_pep604_annotation.rs

@@ -36,6 +36,11 @@ use crate::fix::edits::pad;
 /// foo: int | str = 1
 /// ```
 ///
+/// ## Fix safety
+/// This rule's fix is marked as unsafe, as it may lead to runtime errors when
+/// alongside libraries that rely on runtime type annotations, like Pydantic,
+/// on Python versions prior to Python 3.10.
+///
 /// ## Options
 /// - `target-version`
 /// - `pyupgrade.keep-runtime-typing`