From 12c61612f7a91df64121dd9c991828c26d665325 Mon Sep 17 00:00:00 2001 From: xFrednet <xFrednet@gmail.com> Date: Fri, 2 Jul 2021 20:37:11 +0200 Subject: [PATCH 1/2] Update lint documentation to use markdown headlines --- clippy_dev/src/new_lint.rs | 9 +- .../src/absurd_extreme_comparisons.rs | 12 +- clippy_lints/src/approx_const.rs | 10 +- clippy_lints/src/arithmetic.rs | 20 +- clippy_lints/src/as_conversions.rs | 10 +- clippy_lints/src/asm_syntax.rs | 20 +- clippy_lints/src/assertions_on_constants.rs | 11 +- clippy_lints/src/assign_ops.rs | 22 +- clippy_lints/src/async_yields_async.rs | 11 +- clippy_lints/src/atomic_ordering.rs | 10 +- clippy_lints/src/attrs.rs | 74 +- clippy_lints/src/await_holding_invalid.rs | 24 +- clippy_lints/src/bit_mask.rs | 32 +- clippy_lints/src/blacklisted_name.rs | 10 +- clippy_lints/src/blocks_in_if_conditions.rs | 10 +- clippy_lints/src/bool_assert_comparison.rs | 11 +- clippy_lints/src/booleans.rs | 22 +- clippy_lints/src/bytecount.rs | 12 +- clippy_lints/src/cargo_common_metadata.rs | 10 +- ...se_sensitive_file_extension_comparisons.rs | 9 +- clippy_lints/src/casts/mod.rs | 116 ++-- clippy_lints/src/checked_conversions.rs | 10 +- clippy_lints/src/cognitive_complexity.rs | 12 +- clippy_lints/src/collapsible_if.rs | 20 +- clippy_lints/src/collapsible_match.rs | 11 +- clippy_lints/src/comparison_chain.rs | 11 +- clippy_lints/src/copies.rs | 40 +- clippy_lints/src/copy_iterator.rs | 10 +- clippy_lints/src/create_dir.rs | 10 +- clippy_lints/src/dbg_macro.rs | 10 +- clippy_lints/src/default.rs | 21 +- clippy_lints/src/default_numeric_fallback.rs | 11 +- clippy_lints/src/deprecated_lints.rs | 96 ++- clippy_lints/src/dereference.rs | 8 +- clippy_lints/src/derive.rs | 43 +- clippy_lints/src/disallowed_method.rs | 11 +- clippy_lints/src/disallowed_script_idents.rs | 10 +- clippy_lints/src/disallowed_type.rs | 11 +- clippy_lints/src/doc.rs | 53 +- clippy_lints/src/double_comparison.rs | 10 +- clippy_lints/src/double_parens.rs | 10 +- clippy_lints/src/drop_forget_ref.rs | 40 +- clippy_lints/src/duration_subsec.rs | 10 +- clippy_lints/src/else_if_without_else.rs | 10 +- clippy_lints/src/empty_enum.rs | 11 +- clippy_lints/src/entry.rs | 11 +- clippy_lints/src/enum_clike.rs | 10 +- clippy_lints/src/enum_variants.rs | 30 +- clippy_lints/src/eq_op.rs | 22 +- clippy_lints/src/erasing_op.rs | 10 +- clippy_lints/src/escape.rs | 10 +- clippy_lints/src/eta_reduction.rs | 22 +- clippy_lints/src/eval_order_dependence.rs | 22 +- clippy_lints/src/excessive_bools.rs | 20 +- clippy_lints/src/exhaustive_items.rs | 22 +- clippy_lints/src/exit.rs | 10 +- clippy_lints/src/explicit_write.rs | 10 +- clippy_lints/src/fallible_impl_from.rs | 10 +- .../src/float_equality_without_abs.rs | 50 +- clippy_lints/src/float_literal.rs | 22 +- clippy_lints/src/floating_point_arithmetic.rs | 22 +- clippy_lints/src/format.rs | 10 +- clippy_lints/src/formatting.rs | 40 +- clippy_lints/src/from_over_into.rs | 11 +- clippy_lints/src/from_str_radix_10.rs | 12 +- clippy_lints/src/functions/mod.rs | 73 +- clippy_lints/src/future_not_send.rs | 11 +- clippy_lints/src/get_last_with_len.rs | 11 +- clippy_lints/src/identity_op.rs | 10 +- clippy_lints/src/if_let_mutex.rs | 11 +- clippy_lints/src/if_let_some_result.rs | 10 +- clippy_lints/src/if_not_else.rs | 10 +- clippy_lints/src/if_then_some_else_none.rs | 11 +- clippy_lints/src/implicit_hasher.rs | 11 +- clippy_lints/src/implicit_return.rs | 10 +- clippy_lints/src/implicit_saturating_sub.rs | 11 +- .../src/inconsistent_struct_constructor.rs | 11 +- clippy_lints/src/indexing_slicing.rs | 22 +- clippy_lints/src/infinite_iter.rs | 21 +- clippy_lints/src/inherent_impl.rs | 10 +- clippy_lints/src/inherent_to_string.rs | 24 +- clippy_lints/src/inline_fn_without_body.rs | 10 +- clippy_lints/src/int_plus_one.rs | 10 +- clippy_lints/src/integer_division.rs | 10 +- .../src/invalid_upcast_comparisons.rs | 10 +- clippy_lints/src/items_after_statements.rs | 10 +- clippy_lints/src/large_const_arrays.rs | 10 +- clippy_lints/src/large_enum_variant.rs | 12 +- clippy_lints/src/large_stack_arrays.rs | 10 +- clippy_lints/src/len_zero.rs | 30 +- clippy_lints/src/let_if_seq.rs | 10 +- clippy_lints/src/let_underscore.rs | 30 +- clippy_lints/src/lib.rs | 11 +- clippy_lints/src/lifetimes.rs | 20 +- clippy_lints/src/literal_representation.rs | 66 +- clippy_lints/src/loops/mod.rs | 182 ++--- clippy_lints/src/macro_use.rs | 10 +- clippy_lints/src/main_recursion.rs | 10 +- clippy_lints/src/manual_async_fn.rs | 11 +- clippy_lints/src/manual_map.rs | 11 +- clippy_lints/src/manual_non_exhaustive.rs | 11 +- clippy_lints/src/manual_ok_or.rs | 10 +- clippy_lints/src/manual_strip.rs | 10 +- clippy_lints/src/manual_unwrap_or.rs | 8 +- clippy_lints/src/map_clone.rs | 11 +- clippy_lints/src/map_err_ignore.rs | 10 +- clippy_lints/src/map_unit_fn.rs | 22 +- clippy_lints/src/match_on_vec_items.rs | 10 +- clippy_lints/src/matches.rs | 170 ++--- clippy_lints/src/mem_discriminant.rs | 10 +- clippy_lints/src/mem_forget.rs | 10 +- clippy_lints/src/mem_replace.rs | 31 +- clippy_lints/src/methods/mod.rs | 636 +++++++++--------- clippy_lints/src/minmax.rs | 10 +- clippy_lints/src/misc.rs | 93 +-- clippy_lints/src/misc_early/mod.rs | 90 +-- clippy_lints/src/missing_const_for_fn.rs | 12 +- clippy_lints/src/missing_doc.rs | 8 +- .../src/missing_enforced_import_rename.rs | 11 +- clippy_lints/src/missing_inline.rs | 10 +- clippy_lints/src/modulo_arithmetic.rs | 10 +- clippy_lints/src/multiple_crate_versions.rs | 11 +- clippy_lints/src/mut_key.rs | 11 +- clippy_lints/src/mut_mut.rs | 10 +- clippy_lints/src/mut_mutex_lock.rs | 11 +- clippy_lints/src/mut_reference.rs | 10 +- clippy_lints/src/mutable_debug_assertion.rs | 10 +- clippy_lints/src/mutex_atomic.rs | 22 +- .../src/needless_arbitrary_self_type.rs | 10 +- clippy_lints/src/needless_bitwise_bool.rs | 9 +- clippy_lints/src/needless_bool.rs | 21 +- clippy_lints/src/needless_borrow.rs | 20 +- clippy_lints/src/needless_borrowed_ref.rs | 11 +- clippy_lints/src/needless_continue.rs | 10 +- clippy_lints/src/needless_for_each.rs | 11 +- clippy_lints/src/needless_pass_by_value.rs | 10 +- clippy_lints/src/needless_question_mark.rs | 10 +- clippy_lints/src/needless_update.rs | 10 +- clippy_lints/src/neg_cmp_op_on_partial_ord.rs | 9 +- clippy_lints/src/neg_multiply.rs | 11 +- clippy_lints/src/new_without_default.rs | 11 +- clippy_lints/src/no_effect.rs | 20 +- clippy_lints/src/non_copy_const.rs | 22 +- clippy_lints/src/non_expressive_names.rs | 30 +- .../src/non_octal_unix_permissions.rs | 11 +- clippy_lints/src/nonstandard_macro_braces.rs | 12 +- clippy_lints/src/open_options.rs | 10 +- clippy_lints/src/option_env_unwrap.rs | 11 +- clippy_lints/src/option_if_let_else.rs | 9 +- .../src/overflow_check_conditional.rs | 10 +- clippy_lints/src/panic_in_result_fn.rs | 12 +- clippy_lints/src/panic_unimplemented.rs | 40 +- clippy_lints/src/partialeq_ne_impl.rs | 10 +- clippy_lints/src/pass_by_ref_or_value.rs | 20 +- clippy_lints/src/path_buf_push_overwrite.rs | 10 +- clippy_lints/src/pattern_type_mismatch.rs | 11 +- clippy_lints/src/precedence.rs | 10 +- clippy_lints/src/ptr.rs | 42 +- clippy_lints/src/ptr_eq.rs | 11 +- clippy_lints/src/ptr_offset_with_cast.rs | 10 +- clippy_lints/src/question_mark.rs | 10 +- clippy_lints/src/ranges.rs | 54 +- clippy_lints/src/redundant_clone.rs | 11 +- clippy_lints/src/redundant_closure_call.rs | 10 +- clippy_lints/src/redundant_else.rs | 12 +- clippy_lints/src/redundant_field_names.rs | 10 +- clippy_lints/src/redundant_pub_crate.rs | 11 +- clippy_lints/src/redundant_slicing.rs | 12 +- .../src/redundant_static_lifetimes.rs | 10 +- clippy_lints/src/ref_option_ref.rs | 12 +- clippy_lints/src/reference.rs | 19 +- clippy_lints/src/regex.rs | 21 +- clippy_lints/src/repeat_once.rs | 11 +- clippy_lints/src/returns.rs | 20 +- clippy_lints/src/self_assignment.rs | 12 +- clippy_lints/src/self_named_constructor.rs | 11 +- .../src/semicolon_if_nothing_returned.rs | 11 +- clippy_lints/src/serde_api.rs | 11 +- clippy_lints/src/shadow.rs | 33 +- .../src/single_component_path_imports.rs | 11 +- clippy_lints/src/size_of_in_element_count.rs | 10 +- .../src/slow_vector_initialization.rs | 10 +- clippy_lints/src/stable_sort_primitive.rs | 10 +- clippy_lints/src/strings.rs | 63 +- clippy_lints/src/strlen_on_c_strings.rs | 11 +- .../src/suspicious_operation_groupings.rs | 11 +- clippy_lints/src/suspicious_trait_impl.rs | 20 +- clippy_lints/src/swap.rs | 20 +- clippy_lints/src/tabs_in_doc_comments.rs | 10 +- clippy_lints/src/temporary_assignment.rs | 10 +- clippy_lints/src/to_digit_is_some.rs | 8 +- clippy_lints/src/to_string_in_display.rs | 10 +- clippy_lints/src/trait_bounds.rs | 20 +- clippy_lints/src/transmute/mod.rs | 122 ++-- clippy_lints/src/transmuting_null.rs | 11 +- clippy_lints/src/try_err.rs | 10 +- clippy_lints/src/types/mod.rs | 94 +-- clippy_lints/src/undropped_manually_drops.rs | 12 +- clippy_lints/src/unicode.rs | 32 +- clippy_lints/src/unit_return_expecting_ord.rs | 12 +- clippy_lints/src/unit_types/mod.rs | 30 +- clippy_lints/src/unnamed_address.rs | 22 +- clippy_lints/src/unnecessary_self_imports.rs | 12 +- clippy_lints/src/unnecessary_sort_by.rs | 9 +- clippy_lints/src/unnecessary_wraps.rs | 12 +- clippy_lints/src/unnested_or_patterns.rs | 11 +- clippy_lints/src/unsafe_removed_from_name.rs | 10 +- clippy_lints/src/unused_async.rs | 11 +- clippy_lints/src/unused_io_amount.rs | 11 +- clippy_lints/src/unused_self.rs | 10 +- clippy_lints/src/unused_unit.rs | 10 +- clippy_lints/src/unwrap.rs | 21 +- clippy_lints/src/unwrap_in_result.rs | 11 +- clippy_lints/src/upper_case_acronyms.rs | 12 +- clippy_lints/src/use_self.rs | 11 +- clippy_lints/src/useless_conversion.rs | 11 +- clippy_lints/src/utils/author.rs | 5 +- clippy_lints/src/utils/inspector.rs | 5 +- clippy_lints/src/utils/internal_lints.rs | 109 +-- .../internal_lints/metadata_collector.rs | 16 +- clippy_lints/src/vec.rs | 10 +- clippy_lints/src/vec_init_then_push.rs | 11 +- clippy_lints/src/vec_resize_to_zero.rs | 10 +- clippy_lints/src/verbose_file_reads.rs | 11 +- clippy_lints/src/wildcard_dependencies.rs | 11 +- clippy_lints/src/wildcard_imports.rs | 26 +- clippy_lints/src/write.rs | 92 +-- clippy_lints/src/zero_div_zero.rs | 10 +- clippy_lints/src/zero_sized_map_values.rs | 11 +- doc/adding_lints.md | 20 +- 230 files changed, 2717 insertions(+), 2474 deletions(-) diff --git a/clippy_dev/src/new_lint.rs b/clippy_dev/src/new_lint.rs index 4676c2affad79..3a81aaba6de04 100644 --- a/clippy_dev/src/new_lint.rs +++ b/clippy_dev/src/new_lint.rs @@ -169,14 +169,11 @@ use rustc_session::{{declare_lint_pass, declare_tool_lint}}; {pass_import} declare_clippy_lint! {{ - /// **What it does:** + /// ### What it does /// - /// **Why is this bad?** - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? /// + /// ### Example /// ```rust /// // example code where clippy issues a warning /// ``` diff --git a/clippy_lints/src/absurd_extreme_comparisons.rs b/clippy_lints/src/absurd_extreme_comparisons.rs index 49d4350123f4b..1483f3f9185ae 100644 --- a/clippy_lints/src/absurd_extreme_comparisons.rs +++ b/clippy_lints/src/absurd_extreme_comparisons.rs @@ -11,24 +11,26 @@ use clippy_utils::ty::is_isize_or_usize; use clippy_utils::{clip, int_bits, unsext}; declare_clippy_lint! { - /// **What it does:** Checks for comparisons where one side of the relation is + /// ### What it does + /// Checks for comparisons where one side of the relation is /// either the minimum or maximum value for its type and warns if it involves a /// case that is always true or always false. Only integer and boolean types are /// checked. /// - /// **Why is this bad?** An expression like `min <= x` may misleadingly imply + /// ### Why is this bad? + /// An expression like `min <= x` may misleadingly imply /// that it is possible for `x` to be less than the minimum. Expressions like /// `max < x` are probably mistakes. /// - /// **Known problems:** For `usize` the size of the current compile target will + /// ### Known problems + /// For `usize` the size of the current compile target will /// be assumed (e.g., 64 bits on 64 bit systems). This means code that uses such /// a comparison to detect target pointer width will trigger this lint. One can /// use `mem::sizeof` and compare its value or conditional compilation /// attributes /// like `#[cfg(target_pointer_width = "64")] ..` instead. /// - /// **Example:** - /// + /// ### Example /// ```rust /// let vec: Vec<isize> = Vec::new(); /// if vec.len() <= 0 {} diff --git a/clippy_lints/src/approx_const.rs b/clippy_lints/src/approx_const.rs index 3d04abe094d78..6100f4e435a8a 100644 --- a/clippy_lints/src/approx_const.rs +++ b/clippy_lints/src/approx_const.rs @@ -7,21 +7,21 @@ use rustc_span::symbol; use std::f64::consts as f64; declare_clippy_lint! { - /// **What it does:** Checks for floating point literals that approximate + /// ### What it does + /// Checks for floating point literals that approximate /// constants which are defined in /// [`std::f32::consts`](https://doc.rust-lang.org/stable/std/f32/consts/#constants) /// or /// [`std::f64::consts`](https://doc.rust-lang.org/stable/std/f64/consts/#constants), /// respectively, suggesting to use the predefined constant. /// - /// **Why is this bad?** Usually, the definition in the standard library is more + /// ### Why is this bad? + /// Usually, the definition in the standard library is more /// precise than what people come up with. If you find that your definition is /// actually more precise, please [file a Rust /// issue](https://github.com/rust-lang/rust/issues). /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x = 3.14; /// let y = 1_f64 / x; diff --git a/clippy_lints/src/arithmetic.rs b/clippy_lints/src/arithmetic.rs index 24c2a9728111f..36fe7b7a86754 100644 --- a/clippy_lints/src/arithmetic.rs +++ b/clippy_lints/src/arithmetic.rs @@ -6,7 +6,8 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::source_map::Span; declare_clippy_lint! { - /// **What it does:** Checks for integer arithmetic operations which could overflow or panic. + /// ### What it does + /// Checks for integer arithmetic operations which could overflow or panic. /// /// Specifically, checks for any operators (`+`, `-`, `*`, `<<`, etc) which are capable /// of overflowing according to the [Rust @@ -14,13 +15,12 @@ declare_clippy_lint! { /// or which can panic (`/`, `%`). No bounds analysis or sophisticated reasoning is /// attempted. /// - /// **Why is this bad?** Integer overflow will trigger a panic in debug builds or will wrap in + /// ### Why is this bad? + /// Integer overflow will trigger a panic in debug builds or will wrap in /// release mode. Division by zero will cause a panic in either mode. In some applications one /// wants explicitly checked, wrapping or saturating arithmetic. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let a = 0; /// a + 1; @@ -31,14 +31,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for float arithmetic. + /// ### What it does + /// Checks for float arithmetic. /// - /// **Why is this bad?** For some embedded systems or kernel development, it + /// ### Why is this bad? + /// For some embedded systems or kernel development, it /// can be useful to rule out floating-point numbers. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let a = 0.0; /// a + 1.0; diff --git a/clippy_lints/src/as_conversions.rs b/clippy_lints/src/as_conversions.rs index 4b31e16094e9f..7c39a3e2ce3de 100644 --- a/clippy_lints/src/as_conversions.rs +++ b/clippy_lints/src/as_conversions.rs @@ -5,7 +5,8 @@ use rustc_middle::lint::in_external_macro; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for usage of `as` conversions. + /// ### What it does + /// Checks for usage of `as` conversions. /// /// Note that this lint is specialized in linting *every single* use of `as` /// regardless of whether good alternatives exist or not. @@ -15,14 +16,13 @@ declare_clippy_lint! { /// There is a good explanation the reason why this lint should work in this way and how it is useful /// [in this issue](https://github.com/rust-lang/rust-clippy/issues/5122). /// - /// **Why is this bad?** `as` conversions will perform many kinds of + /// ### Why is this bad? + /// `as` conversions will perform many kinds of /// conversions, including silently lossy conversions and dangerous coercions. /// There are cases when it makes sense to use `as`, so the lint is /// Allow by default. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// let a: u32; /// ... diff --git a/clippy_lints/src/asm_syntax.rs b/clippy_lints/src/asm_syntax.rs index b970c71b753ce..825832eb79dab 100644 --- a/clippy_lints/src/asm_syntax.rs +++ b/clippy_lints/src/asm_syntax.rs @@ -53,14 +53,14 @@ fn check_expr_asm_syntax(lint: &'static Lint, cx: &EarlyContext<'_>, expr: &Expr } declare_clippy_lint! { - /// **What it does:** Checks for usage of Intel x86 assembly syntax. + /// ### What it does + /// Checks for usage of Intel x86 assembly syntax. /// - /// **Why is this bad?** The lint has been enabled to indicate a preference + /// ### Why is this bad? + /// The lint has been enabled to indicate a preference /// for AT&T x86 assembly syntax. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// /// ```rust,no_run /// # #![feature(asm)] @@ -89,14 +89,14 @@ impl EarlyLintPass for InlineAsmX86IntelSyntax { } declare_clippy_lint! { - /// **What it does:** Checks for usage of AT&T x86 assembly syntax. + /// ### What it does + /// Checks for usage of AT&T x86 assembly syntax. /// - /// **Why is this bad?** The lint has been enabled to indicate a preference + /// ### Why is this bad? + /// The lint has been enabled to indicate a preference /// for Intel x86 assembly syntax. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// /// ```rust,no_run /// # #![feature(asm)] diff --git a/clippy_lints/src/assertions_on_constants.rs b/clippy_lints/src/assertions_on_constants.rs index 5235b2642d18c..cb9347a923d87 100644 --- a/clippy_lints/src/assertions_on_constants.rs +++ b/clippy_lints/src/assertions_on_constants.rs @@ -8,14 +8,17 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for `assert!(true)` and `assert!(false)` calls. + /// ### What it does + /// Checks for `assert!(true)` and `assert!(false)` calls. /// - /// **Why is this bad?** Will be optimized out by the compiler or should probably be replaced by a + /// ### Why is this bad? + /// Will be optimized out by the compiler or should probably be replaced by a /// `panic!()` or `unreachable!()` /// - /// **Known problems:** None + /// ### Known problems + /// None /// - /// **Example:** + /// ### Example /// ```rust,ignore /// assert!(false) /// assert!(true) diff --git a/clippy_lints/src/assign_ops.rs b/clippy_lints/src/assign_ops.rs index 17ce3cd809f6f..2097a1feff9f3 100644 --- a/clippy_lints/src/assign_ops.rs +++ b/clippy_lints/src/assign_ops.rs @@ -12,15 +12,18 @@ use rustc_middle::hir::map::Map; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for `a = a op b` or `a = b commutative_op a` + /// ### What it does + /// Checks for `a = a op b` or `a = b commutative_op a` /// patterns. /// - /// **Why is this bad?** These can be written as the shorter `a op= b`. + /// ### Why is this bad? + /// These can be written as the shorter `a op= b`. /// - /// **Known problems:** While forbidden by the spec, `OpAssign` traits may have + /// ### Known problems + /// While forbidden by the spec, `OpAssign` traits may have /// implementations that differ from the regular `Op` impl. /// - /// **Example:** + /// ### Example /// ```rust /// let mut a = 5; /// let b = 0; @@ -37,17 +40,20 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `a op= a op b` or `a op= b op a` patterns. + /// ### What it does + /// Checks for `a op= a op b` or `a op= b op a` patterns. /// - /// **Why is this bad?** Most likely these are bugs where one meant to write `a + /// ### Why is this bad? + /// Most likely these are bugs where one meant to write `a /// op= b`. /// - /// **Known problems:** Clippy cannot know for sure if `a op= a op b` should have + /// ### Known problems + /// Clippy cannot know for sure if `a op= a op b` should have /// been `a = a op a op b` or `a = a op b`/`a op= b`. Therefore, it suggests both. /// If `a op= a op b` is really the correct behaviour it should be /// written as `a = a op a op b` as it's less confusing. /// - /// **Example:** + /// ### Example /// ```rust /// let mut a = 5; /// let b = 2; diff --git a/clippy_lints/src/async_yields_async.rs b/clippy_lints/src/async_yields_async.rs index e6c7c68f91a07..182736a5a205a 100644 --- a/clippy_lints/src/async_yields_async.rs +++ b/clippy_lints/src/async_yields_async.rs @@ -7,15 +7,14 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for async blocks that yield values of types + /// ### What it does + /// Checks for async blocks that yield values of types /// that can themselves be awaited. /// - /// **Why is this bad?** An await is likely missing. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// An await is likely missing. /// + /// ### Example /// ```rust /// async fn foo() {} /// diff --git a/clippy_lints/src/atomic_ordering.rs b/clippy_lints/src/atomic_ordering.rs index 7ceb01f5590fc..cece28e8b3c3f 100644 --- a/clippy_lints/src/atomic_ordering.rs +++ b/clippy_lints/src/atomic_ordering.rs @@ -8,16 +8,16 @@ use rustc_middle::ty; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for usage of invalid atomic + /// ### What it does + /// Checks for usage of invalid atomic /// ordering in atomic loads/stores/exchanges/updates and /// memory fences. /// - /// **Why is this bad?** Using an invalid atomic ordering + /// ### Why is this bad? + /// Using an invalid atomic ordering /// will cause a panic at run-time. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,no_run /// # use std::sync::atomic::{self, AtomicU8, Ordering}; /// diff --git a/clippy_lints/src/attrs.rs b/clippy_lints/src/attrs.rs index f272ed010a1b0..c9ff468874b58 100644 --- a/clippy_lints/src/attrs.rs +++ b/clippy_lints/src/attrs.rs @@ -41,10 +41,12 @@ static UNIX_SYSTEMS: &[&str] = &[ static NON_UNIX_SYSTEMS: &[&str] = &["hermit", "none", "wasi"]; declare_clippy_lint! { - /// **What it does:** Checks for items annotated with `#[inline(always)]`, + /// ### What it does + /// Checks for items annotated with `#[inline(always)]`, /// unless the annotated function is empty or simply panics. /// - /// **Why is this bad?** While there are valid uses of this annotation (and once + /// ### Why is this bad? + /// While there are valid uses of this annotation (and once /// you know when to use it, by all means `allow` this lint), it's a common /// newbie-mistake to pepper one's code with it. /// @@ -52,11 +54,12 @@ declare_clippy_lint! { /// measure if that additional function call really affects your runtime profile /// sufficiently to make up for the increase in compile time. /// - /// **Known problems:** False positives, big time. This lint is meant to be + /// ### Known problems + /// False positives, big time. This lint is meant to be /// deactivated by everyone doing serious performance work. This means having /// done the measurement. /// - /// **Example:** + /// ### Example /// ```ignore /// #[inline(always)] /// fn not_quite_hot_code(..) { ... } @@ -67,7 +70,8 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `extern crate` and `use` items annotated with + /// ### What it does + /// Checks for `extern crate` and `use` items annotated with /// lint attributes. /// /// This lint permits `#[allow(unused_imports)]`, `#[allow(deprecated)]`, @@ -75,12 +79,11 @@ declare_clippy_lint! { /// `#[allow(clippy::enum_glob_use)]` on `use` items and `#[allow(unused_imports)]` on /// `extern crate` items with a `#[macro_use]` attribute. /// - /// **Why is this bad?** Lint attributes have no effect on crate imports. Most + /// ### Why is this bad? + /// Lint attributes have no effect on crate imports. Most /// likely a `!` was forgotten. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// // Bad /// #[deny(dead_code)] @@ -101,15 +104,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `#[deprecated]` annotations with a `since` + /// ### What it does + /// Checks for `#[deprecated]` annotations with a `since` /// field that is not a valid semantic version. /// - /// **Why is this bad?** For checking the version of the deprecation, it must be + /// ### Why is this bad? + /// For checking the version of the deprecation, it must be /// a valid semver. Failing that, the contained information is useless. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// #[deprecated(since = "forever")] /// fn something_else() { /* ... */ } @@ -120,20 +123,22 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for empty lines after outer attributes + /// ### What it does + /// Checks for empty lines after outer attributes /// - /// **Why is this bad?** + /// ### Why is this bad? /// Most likely the attribute was meant to be an inner attribute using a '!'. /// If it was meant to be an outer attribute, then the following item /// should not be separated by empty lines. /// - /// **Known problems:** Can cause false positives. + /// ### Known problems + /// Can cause false positives. /// /// From the clippy side it's difficult to detect empty lines between an attributes and the /// following item because empty lines and comments are not part of the AST. The parsing /// currently works for basic cases but is not perfect. /// - /// **Example:** + /// ### Example /// ```rust /// // Good (as inner attribute) /// #![allow(dead_code)] @@ -155,14 +160,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `warn`/`deny`/`forbid` attributes targeting the whole clippy::restriction category. + /// ### What it does + /// Checks for `warn`/`deny`/`forbid` attributes targeting the whole clippy::restriction category. /// - /// **Why is this bad?** Restriction lints sometimes are in contrast with other lints or even go against idiomatic rust. + /// ### Why is this bad? + /// Restriction lints sometimes are in contrast with other lints or even go against idiomatic rust. /// These lints should only be enabled on a lint-by-lint basis and with careful consideration. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// Bad: /// ```rust /// #![deny(clippy::restriction)] @@ -178,18 +183,20 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `#[cfg_attr(rustfmt, rustfmt_skip)]` and suggests to replace it + /// ### What it does + /// Checks for `#[cfg_attr(rustfmt, rustfmt_skip)]` and suggests to replace it /// with `#[rustfmt::skip]`. /// - /// **Why is this bad?** Since tool_attributes ([rust-lang/rust#44690](https://github.com/rust-lang/rust/issues/44690)) + /// ### Why is this bad? + /// Since tool_attributes ([rust-lang/rust#44690](https://github.com/rust-lang/rust/issues/44690)) /// are stable now, they should be used instead of the old `cfg_attr(rustfmt)` attributes. /// - /// **Known problems:** This lint doesn't detect crate level inner attributes, because they get + /// ### Known problems + /// This lint doesn't detect crate level inner attributes, because they get /// processed before the PreExpansionPass lints get executed. See /// [#3123](https://github.com/rust-lang/rust-clippy/pull/3123#issuecomment-422321765) /// - /// **Example:** - /// + /// ### Example /// Bad: /// ```rust /// #[cfg_attr(rustfmt, rustfmt_skip)] @@ -207,15 +214,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for cfg attributes having operating systems used in target family position. + /// ### What it does + /// Checks for cfg attributes having operating systems used in target family position. /// - /// **Why is this bad?** The configuration option will not be recognised and the related item will not be included + /// ### Why is this bad? + /// The configuration option will not be recognised and the related item will not be included /// by the conditional compilation engine. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// Bad: /// ```rust /// #[cfg(linux)] diff --git a/clippy_lints/src/await_holding_invalid.rs b/clippy_lints/src/await_holding_invalid.rs index 1739a57a240b2..0cc79c8b6e8cb 100644 --- a/clippy_lints/src/await_holding_invalid.rs +++ b/clippy_lints/src/await_holding_invalid.rs @@ -8,10 +8,12 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** Checks for calls to await while holding a + /// ### What it does + /// Checks for calls to await while holding a /// non-async-aware MutexGuard. /// - /// **Why is this bad?** The Mutex types found in std::sync and parking_lot + /// ### Why is this bad? + /// The Mutex types found in std::sync and parking_lot /// are not designed to operate in an async context across await points. /// /// There are two potential solutions. One is to use an asynx-aware Mutex @@ -19,10 +21,10 @@ declare_clippy_lint! { /// other solution is to ensure the mutex is unlocked before calling await, /// either by introducing a scope or an explicit call to Drop::drop. /// - /// **Known problems:** Will report false positive for explicitly dropped guards ([#6446](https://github.com/rust-lang/rust-clippy/issues/6446)). - /// - /// **Example:** + /// ### Known problems + /// Will report false positive for explicitly dropped guards ([#6446](https://github.com/rust-lang/rust-clippy/issues/6446)). /// + /// ### Example /// ```rust,ignore /// use std::sync::Mutex; /// @@ -51,17 +53,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for calls to await while holding a + /// ### What it does + /// Checks for calls to await while holding a /// `RefCell` `Ref` or `RefMut`. /// - /// **Why is this bad?** `RefCell` refs only check for exclusive mutable access + /// ### Why is this bad? + /// `RefCell` refs only check for exclusive mutable access /// at runtime. Holding onto a `RefCell` ref across an `await` suspension point /// risks panics from a mutable ref shared while other refs are outstanding. /// - /// **Known problems:** Will report false positive for explicitly dropped refs ([#6353](https://github.com/rust-lang/rust-clippy/issues/6353)). - /// - /// **Example:** + /// ### Known problems + /// Will report false positive for explicitly dropped refs ([#6353](https://github.com/rust-lang/rust-clippy/issues/6353)). /// + /// ### Example /// ```rust,ignore /// use std::cell::RefCell; /// diff --git a/clippy_lints/src/bit_mask.rs b/clippy_lints/src/bit_mask.rs index 991ed94572c7e..11346e7c96af9 100644 --- a/clippy_lints/src/bit_mask.rs +++ b/clippy_lints/src/bit_mask.rs @@ -10,7 +10,8 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::source_map::Span; declare_clippy_lint! { - /// **What it does:** Checks for incompatible bit masks in comparisons. + /// ### What it does + /// Checks for incompatible bit masks in comparisons. /// /// The formula for detecting if an expression of the type `_ <bit_op> m /// <cmp_op> c` (where `<bit_op>` is one of {`&`, `|`} and `<cmp_op>` is one of @@ -26,7 +27,8 @@ declare_clippy_lint! { /// |`<` or `>=`| `|` |`x | 1 < 1` |`false` |`m >= c` | /// |`<=` or `>` | `|` |`x | 1 > 0` |`true` |`m > c` | /// - /// **Why is this bad?** If the bits that the comparison cares about are always + /// ### Why is this bad? + /// If the bits that the comparison cares about are always /// set to zero or one by the bit mask, the comparison is constant `true` or /// `false` (depending on mask, compared value, and operators). /// @@ -34,9 +36,7 @@ declare_clippy_lint! { /// this intentionally is to win an underhanded Rust contest or create a /// test-case for this lint. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let x = 1; /// if (x & 1 == 2) { } @@ -47,7 +47,8 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for bit masks in comparisons which can be removed + /// ### What it does + /// Checks for bit masks in comparisons which can be removed /// without changing the outcome. The basic structure can be seen in the /// following table: /// @@ -56,16 +57,18 @@ declare_clippy_lint! { /// |`>` / `<=`|`|` / `^`|`x | 2 > 3`|`x > 3`| /// |`<` / `>=`|`|` / `^`|`x ^ 1 < 4`|`x < 4`| /// - /// **Why is this bad?** Not equally evil as [`bad_bit_mask`](#bad_bit_mask), + /// ### Why is this bad? + /// Not equally evil as [`bad_bit_mask`](#bad_bit_mask), /// but still a bit misleading, because the bit mask is ineffective. /// - /// **Known problems:** False negatives: This lint will only match instances + /// ### Known problems + /// False negatives: This lint will only match instances /// where we have figured out the math (which is for a power-of-two compared /// value). This means things like `x | 1 >= 7` (which would be better written /// as `x >= 6`) will not be reported (but bit masks like this are fairly /// uncommon). /// - /// **Example:** + /// ### Example /// ```rust /// # let x = 1; /// if (x | 1 > 3) { } @@ -76,15 +79,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for bit masks that can be replaced by a call + /// ### What it does + /// Checks for bit masks that can be replaced by a call /// to `trailing_zeros` /// - /// **Why is this bad?** `x.trailing_zeros() > 4` is much clearer than `x & 15 + /// ### Why is this bad? + /// `x.trailing_zeros() > 4` is much clearer than `x & 15 /// == 0` /// - /// **Known problems:** llvm generates better code for `x & 15 == 0` on x86 + /// ### Known problems + /// llvm generates better code for `x & 15 == 0` on x86 /// - /// **Example:** + /// ### Example /// ```rust /// # let x = 1; /// if x & 0b1111 == 0 { } diff --git a/clippy_lints/src/blacklisted_name.rs b/clippy_lints/src/blacklisted_name.rs index 8eb94f3c28e44..916c78c982ae4 100644 --- a/clippy_lints/src/blacklisted_name.rs +++ b/clippy_lints/src/blacklisted_name.rs @@ -5,15 +5,15 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_tool_lint, impl_lint_pass}; declare_clippy_lint! { - /// **What it does:** Checks for usage of blacklisted names for variables, such + /// ### What it does + /// Checks for usage of blacklisted names for variables, such /// as `foo`. /// - /// **Why is this bad?** These names are usually placeholder names and should be + /// ### Why is this bad? + /// These names are usually placeholder names and should be /// avoided. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let foo = 3.14; /// ``` diff --git a/clippy_lints/src/blocks_in_if_conditions.rs b/clippy_lints/src/blocks_in_if_conditions.rs index badcf8d2a43cd..9b2e4f8998e4e 100644 --- a/clippy_lints/src/blocks_in_if_conditions.rs +++ b/clippy_lints/src/blocks_in_if_conditions.rs @@ -13,14 +13,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for `if` conditions that use blocks containing an + /// ### What it does + /// Checks for `if` conditions that use blocks containing an /// expression, statements or conditions that use closures with blocks. /// - /// **Why is this bad?** Style, using blocks in the condition makes it hard to read. + /// ### Why is this bad? + /// Style, using blocks in the condition makes it hard to read. /// - /// **Known problems:** None. - /// - /// **Examples:** + /// ### Examples /// ```rust /// // Bad /// if { true } { /* ... */ } diff --git a/clippy_lints/src/bool_assert_comparison.rs b/clippy_lints/src/bool_assert_comparison.rs index bee706ed40215..8d3f68565b223 100644 --- a/clippy_lints/src/bool_assert_comparison.rs +++ b/clippy_lints/src/bool_assert_comparison.rs @@ -6,14 +6,13 @@ use rustc_lint::{EarlyContext, EarlyLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** This lint warns about boolean comparisons in assert-like macros. + /// ### What it does + /// This lint warns about boolean comparisons in assert-like macros. /// - /// **Why is this bad?** It is shorter to use the equivalent. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// It is shorter to use the equivalent. /// + /// ### Example /// ```rust /// // Bad /// assert_eq!("a".is_empty(), false); diff --git a/clippy_lints/src/booleans.rs b/clippy_lints/src/booleans.rs index e72399af232b5..4a83d35a568c5 100644 --- a/clippy_lints/src/booleans.rs +++ b/clippy_lints/src/booleans.rs @@ -14,16 +14,19 @@ use rustc_span::source_map::Span; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for boolean expressions that can be written more + /// ### What it does + /// Checks for boolean expressions that can be written more /// concisely. /// - /// **Why is this bad?** Readability of boolean expressions suffers from + /// ### Why is this bad? + /// Readability of boolean expressions suffers from /// unnecessary duplication. /// - /// **Known problems:** Ignores short circuiting behavior of `||` and + /// ### Known problems + /// Ignores short circuiting behavior of `||` and /// `&&`. Ignores `|`, `&` and `^`. /// - /// **Example:** + /// ### Example /// ```ignore /// if a && true // should be: if a /// if !(a == b) // should be: if a != b @@ -34,14 +37,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for boolean expressions that contain terminals that + /// ### What it does + /// Checks for boolean expressions that contain terminals that /// can be eliminated. /// - /// **Why is this bad?** This is most likely a logic bug. + /// ### Why is this bad? + /// This is most likely a logic bug. /// - /// **Known problems:** Ignores short circuiting behavior. + /// ### Known problems + /// Ignores short circuiting behavior. /// - /// **Example:** + /// ### Example /// ```ignore /// if a && b || a { ... } /// ``` diff --git a/clippy_lints/src/bytecount.rs b/clippy_lints/src/bytecount.rs index 4f7ffdcdfb499..c444984bc133a 100644 --- a/clippy_lints/src/bytecount.rs +++ b/clippy_lints/src/bytecount.rs @@ -12,18 +12,20 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for naive byte counts + /// ### What it does + /// Checks for naive byte counts /// - /// **Why is this bad?** The [`bytecount`](https://crates.io/crates/bytecount) + /// ### Why is this bad? + /// The [`bytecount`](https://crates.io/crates/bytecount) /// crate has methods to count your bytes faster, especially for large slices. /// - /// **Known problems:** If you have predominantly small slices, the + /// ### Known problems + /// If you have predominantly small slices, the /// `bytecount::count(..)` method may actually be slower. However, if you can /// ensure that less than 2³²-1 matches arise, the `naive_count_32(..)` can be /// faster in those cases. /// - /// **Example:** - /// + /// ### Example /// ```rust /// # let vec = vec![1_u8]; /// &vec.iter().filter(|x| **x == 0u8).count(); // use bytecount::count instead diff --git a/clippy_lints/src/cargo_common_metadata.rs b/clippy_lints/src/cargo_common_metadata.rs index 21c7b2448cec8..bd5426ba707a8 100644 --- a/clippy_lints/src/cargo_common_metadata.rs +++ b/clippy_lints/src/cargo_common_metadata.rs @@ -9,15 +9,15 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::source_map::DUMMY_SP; declare_clippy_lint! { - /// **What it does:** Checks to see if all common metadata is defined in + /// ### What it does + /// Checks to see if all common metadata is defined in /// `Cargo.toml`. See: https://rust-lang-nursery.github.io/api-guidelines/documentation.html#cargotoml-includes-all-common-metadata-c-metadata /// - /// **Why is this bad?** It will be more difficult for users to discover the + /// ### Why is this bad? + /// It will be more difficult for users to discover the /// purpose of the crate, and key information related to it. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```toml /// # This `Cargo.toml` is missing a description field: /// [package] diff --git a/clippy_lints/src/case_sensitive_file_extension_comparisons.rs b/clippy_lints/src/case_sensitive_file_extension_comparisons.rs index c9ef379be565d..86b32475cebdc 100644 --- a/clippy_lints/src/case_sensitive_file_extension_comparisons.rs +++ b/clippy_lints/src/case_sensitive_file_extension_comparisons.rs @@ -8,17 +8,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::{source_map::Spanned, symbol::sym, Span}; declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// Checks for calls to `ends_with` with possible file extensions /// and suggests to use a case-insensitive approach instead. /// - /// **Why is this bad?** + /// ### Why is this bad? /// `ends_with` is case-sensitive and may not detect files with a valid extension. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// fn is_rust_file(filename: &str) -> bool { /// filename.ends_with(".rs") diff --git a/clippy_lints/src/casts/mod.rs b/clippy_lints/src/casts/mod.rs index ae4fdd12c41e8..27e1bea799353 100644 --- a/clippy_lints/src/casts/mod.rs +++ b/clippy_lints/src/casts/mod.rs @@ -20,7 +20,8 @@ use rustc_semver::RustcVersion; use rustc_session::{declare_tool_lint, impl_lint_pass}; declare_clippy_lint! { - /// **What it does:** Checks for casts from any numerical to a float type where + /// ### What it does + /// Checks for casts from any numerical to a float type where /// the receiving type cannot store all values from the original type without /// rounding errors. This possible rounding is to be expected, so this lint is /// `Allow` by default. @@ -28,13 +29,12 @@ declare_clippy_lint! { /// Basically, this warns on casting any integer with 32 or more bits to `f32` /// or any 64-bit integer to `f64`. /// - /// **Why is this bad?** It's not bad at all. But in some applications it can be + /// ### Why is this bad? + /// It's not bad at all. But in some applications it can be /// helpful to know where precision loss can take place. This lint can help find /// those places in the code. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x = u64::MAX; /// x as f64; @@ -45,17 +45,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for casts from a signed to an unsigned numerical + /// ### What it does + /// Checks for casts from a signed to an unsigned numerical /// type. In this case, negative values wrap around to large positive values, /// which can be quite surprising in practice. However, as the cast works as /// defined, this lint is `Allow` by default. /// - /// **Why is this bad?** Possibly surprising results. You can activate this lint + /// ### Why is this bad? + /// Possibly surprising results. You can activate this lint /// as a one-time check to see where numerical wrapping can arise. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let y: i8 = -1; /// y as u128; // will return 18446744073709551615 @@ -66,17 +66,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for casts between numerical types that may + /// ### What it does + /// Checks for casts between numerical types that may /// truncate large values. This is expected behavior, so the cast is `Allow` by /// default. /// - /// **Why is this bad?** In some problem domains, it is good practice to avoid + /// ### Why is this bad? + /// In some problem domains, it is good practice to avoid /// truncation. This lint can be activated to help assess where additional /// checks could be beneficial. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// fn as_u8(x: u64) -> u8 { /// x as u8 @@ -88,20 +88,20 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for casts from an unsigned type to a signed type of + /// ### What it does + /// Checks for casts from an unsigned type to a signed type of /// the same size. Performing such a cast is a 'no-op' for the compiler, /// i.e., nothing is changed at the bit level, and the binary representation of /// the value is reinterpreted. This can cause wrapping if the value is too big /// for the target signed type. However, the cast works as defined, so this lint /// is `Allow` by default. /// - /// **Why is this bad?** While such a cast is not bad in itself, the results can + /// ### Why is this bad? + /// While such a cast is not bad in itself, the results can /// be surprising when this is not the intended behavior, as demonstrated by the /// example below. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// u32::MAX as i32; // will yield a value of `-1` /// ``` @@ -111,19 +111,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for casts between numerical types that may + /// ### What it does + /// Checks for casts between numerical types that may /// be replaced by safe conversion functions. /// - /// **Why is this bad?** Rust's `as` keyword will perform many kinds of + /// ### Why is this bad? + /// Rust's `as` keyword will perform many kinds of /// conversions, including silently lossy conversions. Conversion functions such /// as `i32::from` will only perform lossless conversions. Using the conversion /// functions prevents conversions from turning into silent lossy conversions if /// the types of the input expressions ever change, and make it easier for /// people reading the code to know that the conversion is lossless. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// fn as_u64(x: u8) -> u64 { /// x as u64 @@ -143,14 +143,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for casts to the same type, casts of int literals to integer types + /// ### What it does + /// Checks for casts to the same type, casts of int literals to integer types /// and casts of float literals to float types. /// - /// **Why is this bad?** It's just unnecessary. - /// - /// **Known problems:** None. + /// ### Why is this bad? + /// It's just unnecessary. /// - /// **Example:** + /// ### Example /// ```rust /// let _ = 2i32 as i32; /// let _ = 0.5 as f32; @@ -168,17 +168,20 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for casts, using `as` or `pointer::cast`, + /// ### What it does + /// Checks for casts, using `as` or `pointer::cast`, /// from a less-strictly-aligned pointer to a more-strictly-aligned pointer /// - /// **Why is this bad?** Dereferencing the resulting pointer may be undefined + /// ### Why is this bad? + /// Dereferencing the resulting pointer may be undefined /// behavior. /// - /// **Known problems:** Using `std::ptr::read_unaligned` and `std::ptr::write_unaligned` or similar + /// ### Known problems + /// Using `std::ptr::read_unaligned` and `std::ptr::write_unaligned` or similar /// on the resulting pointer is fine. Is over-zealous: Casts with manual alignment checks or casts like /// u64-> u8 -> u16 can be fine. Miri is able to do a more in-depth analysis. /// - /// **Example:** + /// ### Example /// ```rust /// let _ = (&1u8 as *const u8) as *const u16; /// let _ = (&mut 1u8 as *mut u8) as *mut u16; @@ -192,9 +195,10 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for casts of function pointers to something other than usize + /// ### What it does + /// Checks for casts of function pointers to something other than usize /// - /// **Why is this bad?** + /// ### Why is this bad? /// Casting a function pointer to anything other than usize/isize is not portable across /// architectures, because you end up losing bits if the target type is too small or end up with a /// bunch of extra bits that waste space and add more instructions to the final binary than @@ -202,8 +206,7 @@ declare_clippy_lint! { /// /// Casting to isize also doesn't make sense since there are no signed addresses. /// - /// **Example** - /// + /// ### Example /// ```rust /// // Bad /// fn fun() -> i32 { 1 } @@ -219,16 +222,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for casts of a function pointer to a numeric type not wide enough to + /// ### What it does + /// Checks for casts of a function pointer to a numeric type not wide enough to /// store address. /// - /// **Why is this bad?** + /// ### Why is this bad? /// Such a cast discards some bits of the function's address. If this is intended, it would be more /// clearly expressed by casting to usize first, then casting the usize to the intended type (with /// a comment) to perform the truncation. /// - /// **Example** - /// + /// ### Example /// ```rust /// // Bad /// fn fn1() -> i16 { @@ -249,15 +252,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for casts of `&T` to `&mut T` anywhere in the code. + /// ### What it does + /// Checks for casts of `&T` to `&mut T` anywhere in the code. /// - /// **Why is this bad?** It’s basically guaranteed to be undefined behaviour. + /// ### Why is this bad? + /// It’s basically guaranteed to be undefined behaviour. /// `UnsafeCell` is the only way to obtain aliasable data that is considered /// mutable. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// fn x(r: &i32) { /// unsafe { @@ -283,18 +286,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for expressions where a character literal is cast + /// ### What it does + /// Checks for expressions where a character literal is cast /// to `u8` and suggests using a byte literal instead. /// - /// **Why is this bad?** In general, casting values to smaller types is + /// ### Why is this bad? + /// In general, casting values to smaller types is /// error-prone and should be avoided where possible. In the particular case of /// converting a character literal to u8, it is easy to avoid by just using a /// byte literal instead. As an added bonus, `b'a'` is even slightly shorter /// than `'a' as u8`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// 'x' as u8 /// ``` @@ -310,18 +313,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// Checks for `as` casts between raw pointers without changing its mutability, /// namely `*const T` to `*const U` and `*mut T` to `*mut U`. /// - /// **Why is this bad?** + /// ### Why is this bad? /// Though `as` casts between raw pointers is not terrible, `pointer::cast` is safer because /// it cannot accidentally change the pointer's mutability nor cast the pointer to other types like `usize`. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// let ptr: *const u32 = &42_u32; /// let mut_ptr: *mut u32 = &mut 42_u32; diff --git a/clippy_lints/src/checked_conversions.rs b/clippy_lints/src/checked_conversions.rs index 8d3123e1ec8ee..842bbf006cca9 100644 --- a/clippy_lints/src/checked_conversions.rs +++ b/clippy_lints/src/checked_conversions.rs @@ -13,13 +13,13 @@ use rustc_semver::RustcVersion; use rustc_session::{declare_tool_lint, impl_lint_pass}; declare_clippy_lint! { - /// **What it does:** Checks for explicit bounds checking when casting. + /// ### What it does + /// Checks for explicit bounds checking when casting. /// - /// **Why is this bad?** Reduces the readability of statements & is error prone. + /// ### Why is this bad? + /// Reduces the readability of statements & is error prone. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let foo: u32 = 5; /// # let _ = diff --git a/clippy_lints/src/cognitive_complexity.rs b/clippy_lints/src/cognitive_complexity.rs index f62c6a9c3251c..96c30d57ee198 100644 --- a/clippy_lints/src/cognitive_complexity.rs +++ b/clippy_lints/src/cognitive_complexity.rs @@ -14,15 +14,19 @@ use rustc_span::source_map::Span; use rustc_span::{sym, BytePos}; declare_clippy_lint! { - /// **What it does:** Checks for methods with high cognitive complexity. + /// ### What it does + /// Checks for methods with high cognitive complexity. /// - /// **Why is this bad?** Methods of high cognitive complexity tend to be hard to + /// ### Why is this bad? + /// Methods of high cognitive complexity tend to be hard to /// both read and maintain. Also LLVM will tend to optimize small methods better. /// - /// **Known problems:** Sometimes it's hard to find a way to reduce the + /// ### Known problems + /// Sometimes it's hard to find a way to reduce the /// complexity. /// - /// **Example:** No. You'll see it when you get the warning. + /// ### Example + /// No. You'll see it when you get the warning. pub COGNITIVE_COMPLEXITY, nursery, "functions that should be split up into multiple functions" diff --git a/clippy_lints/src/collapsible_if.rs b/clippy_lints/src/collapsible_if.rs index 6e95073823908..4aa8798071568 100644 --- a/clippy_lints/src/collapsible_if.rs +++ b/clippy_lints/src/collapsible_if.rs @@ -22,15 +22,15 @@ use rustc_lint::{EarlyContext, EarlyLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for nested `if` statements which can be collapsed + /// ### What it does + /// Checks for nested `if` statements which can be collapsed /// by `&&`-combining their conditions. /// - /// **Why is this bad?** Each `if`-statement adds one level of nesting, which + /// ### Why is this bad? + /// Each `if`-statement adds one level of nesting, which /// makes code look more complex than it really is. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// if x { /// if y { @@ -53,15 +53,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for collapsible `else { if ... }` expressions + /// ### What it does + /// Checks for collapsible `else { if ... }` expressions /// that can be collapsed to `else if ...`. /// - /// **Why is this bad?** Each `if`-statement adds one level of nesting, which + /// ### Why is this bad? + /// Each `if`-statement adds one level of nesting, which /// makes code look more complex than it really is. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// /// if x { diff --git a/clippy_lints/src/collapsible_match.rs b/clippy_lints/src/collapsible_match.rs index a6c3a5b0e83c4..a403a9846babd 100644 --- a/clippy_lints/src/collapsible_match.rs +++ b/clippy_lints/src/collapsible_match.rs @@ -9,18 +9,17 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::{MultiSpan, Span}; declare_clippy_lint! { - /// **What it does:** Finds nested `match` or `if let` expressions where the patterns may be "collapsed" together + /// ### What it does + /// Finds nested `match` or `if let` expressions where the patterns may be "collapsed" together /// without adding any branches. /// /// Note that this lint is not intended to find _all_ cases where nested match patterns can be merged, but only /// cases where merging would most likely make the code more readable. /// - /// **Why is this bad?** It is unnecessarily verbose and complex. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// It is unnecessarily verbose and complex. /// + /// ### Example /// ```rust /// fn func(opt: Option<Result<u64, String>>) { /// let n = match opt { diff --git a/clippy_lints/src/comparison_chain.rs b/clippy_lints/src/comparison_chain.rs index b6999bef6e726..597a3c67024e5 100644 --- a/clippy_lints/src/comparison_chain.rs +++ b/clippy_lints/src/comparison_chain.rs @@ -6,16 +6,19 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks comparison chains written with `if` that can be + /// ### What it does + /// Checks comparison chains written with `if` that can be /// rewritten with `match` and `cmp`. /// - /// **Why is this bad?** `if` is not guaranteed to be exhaustive and conditionals can get + /// ### Why is this bad? + /// `if` is not guaranteed to be exhaustive and conditionals can get /// repetitive /// - /// **Known problems:** The match statement may be slower due to the compiler + /// ### Known problems + /// The match statement may be slower due to the compiler /// not inlining the call to cmp. See issue [#5354](https://github.com/rust-lang/rust-clippy/issues/5354) /// - /// **Example:** + /// ### Example /// ```rust,ignore /// # fn a() {} /// # fn b() {} diff --git a/clippy_lints/src/copies.rs b/clippy_lints/src/copies.rs index 9cbcde597686e..2dcd55457993c 100644 --- a/clippy_lints/src/copies.rs +++ b/clippy_lints/src/copies.rs @@ -16,13 +16,13 @@ use rustc_span::{source_map::Span, symbol::Symbol, BytePos}; use std::borrow::Cow; declare_clippy_lint! { - /// **What it does:** Checks for consecutive `if`s with the same condition. + /// ### What it does + /// Checks for consecutive `if`s with the same condition. /// - /// **Why is this bad?** This is probably a copy & paste error. + /// ### Why is this bad? + /// This is probably a copy & paste error. /// - /// **Known problems:** Hopefully none. - /// - /// **Example:** + /// ### Example /// ```ignore /// if a == b { /// … @@ -47,15 +47,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for consecutive `if`s with the same function call. + /// ### What it does + /// Checks for consecutive `if`s with the same function call. /// - /// **Why is this bad?** This is probably a copy & paste error. + /// ### Why is this bad? + /// This is probably a copy & paste error. /// Despite the fact that function can have side effects and `if` works as /// intended, such an approach is implicit and can be considered a "code smell". /// - /// **Known problems:** Hopefully none. - /// - /// **Example:** + /// ### Example /// ```ignore /// if foo() == bar { /// … @@ -94,14 +94,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `if/else` with the same body as the *then* part + /// ### What it does + /// Checks for `if/else` with the same body as the *then* part /// and the *else* part. /// - /// **Why is this bad?** This is probably a copy & paste error. - /// - /// **Known problems:** Hopefully none. + /// ### Why is this bad? + /// This is probably a copy & paste error. /// - /// **Example:** + /// ### Example /// ```ignore /// let foo = if … { /// 42 @@ -115,17 +115,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks if the `if` and `else` block contain shared code that can be + /// ### What it does + /// Checks if the `if` and `else` block contain shared code that can be /// moved out of the blocks. /// - /// **Why is this bad?** Duplicate code is less maintainable. + /// ### Why is this bad? + /// Duplicate code is less maintainable. /// - /// **Known problems:** + /// ### Known problems /// * The lint doesn't check if the moved expressions modify values that are beeing used in /// the if condition. The suggestion can in that case modify the behavior of the program. /// See [rust-clippy#7452](https://github.com/rust-lang/rust-clippy/issues/7452) /// - /// **Example:** + /// ### Example /// ```ignore /// let foo = if … { /// println!("Hello World"); diff --git a/clippy_lints/src/copy_iterator.rs b/clippy_lints/src/copy_iterator.rs index 35079c6bedc02..c2e9e8b3ab7f3 100644 --- a/clippy_lints/src/copy_iterator.rs +++ b/clippy_lints/src/copy_iterator.rs @@ -8,15 +8,15 @@ use rustc_span::sym; use if_chain::if_chain; declare_clippy_lint! { - /// **What it does:** Checks for types that implement `Copy` as well as + /// ### What it does + /// Checks for types that implement `Copy` as well as /// `Iterator`. /// - /// **Why is this bad?** Implicit copies can be confusing when working with + /// ### Why is this bad? + /// Implicit copies can be confusing when working with /// iterator combinators. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// #[derive(Copy, Clone)] /// struct Countdown(u8); diff --git a/clippy_lints/src/create_dir.rs b/clippy_lints/src/create_dir.rs index 7b5cce6462a43..e4ee27724831d 100644 --- a/clippy_lints/src/create_dir.rs +++ b/clippy_lints/src/create_dir.rs @@ -8,13 +8,13 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks usage of `std::fs::create_dir` and suggest using `std::fs::create_dir_all` instead. + /// ### What it does + /// Checks usage of `std::fs::create_dir` and suggest using `std::fs::create_dir_all` instead. /// - /// **Why is this bad?** Sometimes `std::fs::create_dir` is mistakenly chosen over `std::fs::create_dir_all`. + /// ### Why is this bad? + /// Sometimes `std::fs::create_dir` is mistakenly chosen over `std::fs::create_dir_all`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// /// ```rust /// std::fs::create_dir("foo"); diff --git a/clippy_lints/src/dbg_macro.rs b/clippy_lints/src/dbg_macro.rs index 286cc7e223efb..bab4a696f831e 100644 --- a/clippy_lints/src/dbg_macro.rs +++ b/clippy_lints/src/dbg_macro.rs @@ -8,14 +8,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::source_map::Span; declare_clippy_lint! { - /// **What it does:** Checks for usage of dbg!() macro. + /// ### What it does + /// Checks for usage of dbg!() macro. /// - /// **Why is this bad?** `dbg!` macro is intended as a debugging tool. It + /// ### Why is this bad? + /// `dbg!` macro is intended as a debugging tool. It /// should not be in version control. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// // Bad /// dbg!(true) diff --git a/clippy_lints/src/default.rs b/clippy_lints/src/default.rs index 947479db8f5d7..db8f2171348f7 100644 --- a/clippy_lints/src/default.rs +++ b/clippy_lints/src/default.rs @@ -13,14 +13,14 @@ use rustc_span::symbol::{Ident, Symbol}; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** Checks for literal calls to `Default::default()`. + /// ### What it does + /// Checks for literal calls to `Default::default()`. /// - /// **Why is this bad?** It's more clear to the reader to use the name of the type whose default is + /// ### Why is this bad? + /// It's more clear to the reader to use the name of the type whose default is /// being gotten than the generic `Default`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// // Bad /// let s: String = Default::default(); @@ -34,14 +34,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for immediate reassignment of fields initialized + /// ### What it does + /// Checks for immediate reassignment of fields initialized /// with Default::default(). /// - /// **Why is this bad?**It's more idiomatic to use the [functional update syntax](https://doc.rust-lang.org/reference/expressions/struct-expr.html#functional-update-syntax). + /// ### Why is this bad? + ///It's more idiomatic to use the [functional update syntax](https://doc.rust-lang.org/reference/expressions/struct-expr.html#functional-update-syntax). /// - /// **Known problems:** Assignments to patterns that are of tuple type are not linted. + /// ### Known problems + /// Assignments to patterns that are of tuple type are not linted. /// - /// **Example:** + /// ### Example /// Bad: /// ``` /// # #[derive(Default)] diff --git a/clippy_lints/src/default_numeric_fallback.rs b/clippy_lints/src/default_numeric_fallback.rs index e719a1b0abf87..3f1b7ea6214d4 100644 --- a/clippy_lints/src/default_numeric_fallback.rs +++ b/clippy_lints/src/default_numeric_fallback.rs @@ -18,7 +18,8 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use std::iter; declare_clippy_lint! { - /// **What it does:** Checks for usage of unconstrained numeric literals which may cause default numeric fallback in type + /// ### What it does + /// Checks for usage of unconstrained numeric literals which may cause default numeric fallback in type /// inference. /// /// Default numeric fallback means that if numeric types have not yet been bound to concrete @@ -27,12 +28,14 @@ declare_clippy_lint! { /// /// See [RFC0212](https://github.com/rust-lang/rfcs/blob/master/text/0212-restore-int-fallback.md) for more information about the fallback. /// - /// **Why is this bad?** For those who are very careful about types, default numeric fallback + /// ### Why is this bad? + /// For those who are very careful about types, default numeric fallback /// can be a pitfall that cause unexpected runtime behavior. /// - /// **Known problems:** This lint can only be allowed at the function level or above. + /// ### Known problems + /// This lint can only be allowed at the function level or above. /// - /// **Example:** + /// ### Example /// ```rust /// let i = 10; /// let f = 1.23; diff --git a/clippy_lints/src/deprecated_lints.rs b/clippy_lints/src/deprecated_lints.rs index 2933fbc93418a..c604516742ce5 100644 --- a/clippy_lints/src/deprecated_lints.rs +++ b/clippy_lints/src/deprecated_lints.rs @@ -12,27 +12,33 @@ macro_rules! declare_deprecated_lint { } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** This used to check for `assert!(a == b)` and recommend + /// ### Deprecation reason + /// This used to check for `assert!(a == b)` and recommend /// replacement with `assert_eq!(a, b)`, but this is no longer needed after RFC 2011. pub SHOULD_ASSERT_EQ, "`assert!()` will be more flexible with RFC 2011" } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** This used to check for `Vec::extend`, which was slower than + /// ### Deprecation reason + /// This used to check for `Vec::extend`, which was slower than /// `Vec::extend_from_slice`. Thanks to specialization, this is no longer true. pub EXTEND_FROM_SLICE, "`.extend_from_slice(_)` is a faster way to extend a Vec by a slice" } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** `Range::step_by(0)` used to be linted since it's + /// ### Deprecation reason + /// `Range::step_by(0)` used to be linted since it's /// an infinite iterator, which is better expressed by `iter::repeat`, /// but the method has been removed for `Iterator::step_by` which panics /// if given a zero @@ -41,27 +47,33 @@ declare_deprecated_lint! { } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** This used to check for `Vec::as_slice`, which was unstable with good + /// ### Deprecation reason + /// This used to check for `Vec::as_slice`, which was unstable with good /// stable alternatives. `Vec::as_slice` has now been stabilized. pub UNSTABLE_AS_SLICE, "`Vec::as_slice` has been stabilized in 1.7" } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** This used to check for `Vec::as_mut_slice`, which was unstable with good + /// ### Deprecation reason + /// This used to check for `Vec::as_mut_slice`, which was unstable with good /// stable alternatives. `Vec::as_mut_slice` has now been stabilized. pub UNSTABLE_AS_MUT_SLICE, "`Vec::as_mut_slice` has been stabilized in 1.7" } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** This lint should never have applied to non-pointer types, as transmuting + /// ### Deprecation reason + /// This lint should never have applied to non-pointer types, as transmuting /// between non-pointer types of differing alignment is well-defined behavior (it's semantically /// equivalent to a memcpy). This lint has thus been refactored into two separate lints: /// cast_ptr_alignment and transmute_ptr_to_ptr. @@ -70,9 +82,11 @@ declare_deprecated_lint! { } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** This lint is too subjective, not having a good reason for being in clippy. + /// ### Deprecation reason + /// This lint is too subjective, not having a good reason for being in clippy. /// Additionally, compound assignment operators may be overloaded separately from their non-assigning /// counterparts, so this lint may suggest a change in behavior or the code may not compile. pub ASSIGN_OPS, @@ -80,9 +94,11 @@ declare_deprecated_lint! { } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** The original rule will only lint for `if let`. After + /// ### Deprecation reason + /// The original rule will only lint for `if let`. After /// making it support to lint `match`, naming as `if let` is not suitable for it. /// So, this lint is deprecated. pub IF_LET_REDUNDANT_PATTERN_MATCHING, @@ -90,9 +106,11 @@ declare_deprecated_lint! { } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** This lint used to suggest replacing `let mut vec = + /// ### Deprecation reason + /// This lint used to suggest replacing `let mut vec = /// Vec::with_capacity(n); vec.set_len(n);` with `let vec = vec![0; n];`. The /// replacement has very different performance characteristics so the lint is /// deprecated. @@ -101,51 +119,63 @@ declare_deprecated_lint! { } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** This lint has been superseded by #[must_use] in rustc. + /// ### Deprecation reason + /// This lint has been superseded by #[must_use] in rustc. pub UNUSED_COLLECT, "`collect` has been marked as #[must_use] in rustc and that covers all cases of this lint" } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** Associated-constants are now preferred. + /// ### Deprecation reason + /// Associated-constants are now preferred. pub REPLACE_CONSTS, "associated-constants `MIN`/`MAX` of integers are preferred to `{min,max}_value()` and module constants" } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** The regex! macro does not exist anymore. + /// ### Deprecation reason + /// The regex! macro does not exist anymore. pub REGEX_MACRO, "the regex! macro has been removed from the regex crate in 2018" } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** This lint has been replaced by `manual_find_map`, a + /// ### Deprecation reason + /// This lint has been replaced by `manual_find_map`, a /// more specific lint. pub FIND_MAP, "this lint has been replaced by `manual_find_map`, a more specific lint" } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** This lint has been replaced by `manual_filter_map`, a + /// ### Deprecation reason + /// This lint has been replaced by `manual_filter_map`, a /// more specific lint. pub FILTER_MAP, "this lint has been replaced by `manual_filter_map`, a more specific lint" } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** The `avoid_breaking_exported_api` config option was added, which + /// ### Deprecation reason + /// The `avoid_breaking_exported_api` config option was added, which /// enables the `enum_variant_names` lint for public items. /// ``` pub PUB_ENUM_VARIANT_NAMES, @@ -153,9 +183,11 @@ declare_deprecated_lint! { } declare_deprecated_lint! { - /// **What it does:** Nothing. This lint has been deprecated. + /// ### What it does + /// Nothing. This lint has been deprecated. /// - /// **Deprecation reason:** The `avoid_breaking_exported_api` config option was added, which + /// ### Deprecation reason + /// The `avoid_breaking_exported_api` config option was added, which /// enables the `wrong_self_conversion` lint for public items. pub WRONG_PUB_SELF_CONVENTION, "set the `avoid-breaking-exported-api` config option to `false` to enable the `wrong_self_convention` lint for public items" diff --git a/clippy_lints/src/dereference.rs b/clippy_lints/src/dereference.rs index 682003f9c2c4c..ded7001ad8c86 100644 --- a/clippy_lints/src/dereference.rs +++ b/clippy_lints/src/dereference.rs @@ -11,12 +11,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::{symbol::sym, Span}; declare_clippy_lint! { - /// **What it does:** Checks for explicit `deref()` or `deref_mut()` method calls. + /// ### What it does + /// Checks for explicit `deref()` or `deref_mut()` method calls. /// - /// **Why is this bad?** Dereferencing by `&*x` or `&mut *x` is clearer and more concise, + /// ### Why is this bad? + /// Dereferencing by `&*x` or `&mut *x` is clearer and more concise, /// when not part of a method chain. /// - /// **Example:** + /// ### Example /// ```rust /// use std::ops::Deref; /// let a: &mut String = &mut String::from("foo"); diff --git a/clippy_lints/src/derive.rs b/clippy_lints/src/derive.rs index 7aafaf7138301..dcfa5253f8341 100644 --- a/clippy_lints/src/derive.rs +++ b/clippy_lints/src/derive.rs @@ -15,10 +15,12 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::source_map::Span; declare_clippy_lint! { - /// **What it does:** Checks for deriving `Hash` but implementing `PartialEq` + /// ### What it does + /// Checks for deriving `Hash` but implementing `PartialEq` /// explicitly or vice versa. /// - /// **Why is this bad?** The implementation of these traits must agree (for + /// ### Why is this bad? + /// The implementation of these traits must agree (for /// example for use with `HashMap`) so it’s probably a bad idea to use a /// default-generated `Hash` implementation with an explicitly defined /// `PartialEq`. In particular, the following must hold for any type: @@ -27,9 +29,7 @@ declare_clippy_lint! { /// k1 == k2 ⇒ hash(k1) == hash(k2) /// ``` /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// #[derive(Hash)] /// struct Foo; @@ -44,10 +44,12 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for deriving `Ord` but implementing `PartialOrd` + /// ### What it does + /// Checks for deriving `Ord` but implementing `PartialOrd` /// explicitly or vice versa. /// - /// **Why is this bad?** The implementation of these traits must agree (for + /// ### Why is this bad? + /// The implementation of these traits must agree (for /// example for use with `sort`) so it’s probably a bad idea to use a /// default-generated `Ord` implementation with an explicitly defined /// `PartialOrd`. In particular, the following must hold for any type @@ -57,10 +59,7 @@ declare_clippy_lint! { /// k1.cmp(&k2) == k1.partial_cmp(&k2).unwrap() /// ``` /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust,ignore /// #[derive(Ord, PartialEq, Eq)] /// struct Foo; @@ -95,18 +94,21 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for explicit `Clone` implementations for `Copy` + /// ### What it does + /// Checks for explicit `Clone` implementations for `Copy` /// types. /// - /// **Why is this bad?** To avoid surprising behaviour, these traits should + /// ### Why is this bad? + /// To avoid surprising behaviour, these traits should /// agree and the behaviour of `Copy` cannot be overridden. In almost all /// situations a `Copy` type should have a `Clone` implementation that does /// nothing more than copy the object, which is what `#[derive(Copy, Clone)]` /// gets you. /// - /// **Known problems:** Bounds of generic types are sometimes wrong: https://github.com/rust-lang/rust/issues/26925 + /// ### Known problems + /// Bounds of generic types are sometimes wrong: https://github.com/rust-lang/rust/issues/26925 /// - /// **Example:** + /// ### Example /// ```rust,ignore /// #[derive(Copy)] /// struct Foo; @@ -121,16 +123,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for deriving `serde::Deserialize` on a type that + /// ### What it does + /// Checks for deriving `serde::Deserialize` on a type that /// has methods using `unsafe`. /// - /// **Why is this bad?** Deriving `serde::Deserialize` will create a constructor + /// ### Why is this bad? + /// Deriving `serde::Deserialize` will create a constructor /// that may violate invariants hold by another constructor. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust,ignore /// use serde::Deserialize; /// diff --git a/clippy_lints/src/disallowed_method.rs b/clippy_lints/src/disallowed_method.rs index aa1a609afedc0..7069cb4198ca9 100644 --- a/clippy_lints/src/disallowed_method.rs +++ b/clippy_lints/src/disallowed_method.rs @@ -8,15 +8,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::Symbol; declare_clippy_lint! { - /// **What it does:** Denies the configured methods and functions in clippy.toml + /// ### What it does + /// Denies the configured methods and functions in clippy.toml /// - /// **Why is this bad?** Some methods are undesirable in certain contexts, + /// ### Why is this bad? + /// Some methods are undesirable in certain contexts, /// and it's beneficial to lint for them as needed. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// An example clippy.toml configuration: /// ```toml /// # clippy.toml diff --git a/clippy_lints/src/disallowed_script_idents.rs b/clippy_lints/src/disallowed_script_idents.rs index 12c525634c51d..6d38d30cd0bab 100644 --- a/clippy_lints/src/disallowed_script_idents.rs +++ b/clippy_lints/src/disallowed_script_idents.rs @@ -6,7 +6,8 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use unicode_script::{Script, UnicodeScript}; declare_clippy_lint! { - /// **What it does:** Checks for usage of unicode scripts other than those explicitly allowed + /// ### What it does + /// Checks for usage of unicode scripts other than those explicitly allowed /// by the lint config. /// /// This lint doesn't take into account non-text scripts such as `Unknown` and `Linear_A`. @@ -19,7 +20,8 @@ declare_clippy_lint! { /// [aliases]: http://www.unicode.org/reports/tr24/tr24-31.html#Script_Value_Aliases /// [supported_scripts]: https://www.unicode.org/iso15924/iso15924-codes.html /// - /// **Why is this bad?** It may be not desired to have many different scripts for + /// ### Why is this bad? + /// It may be not desired to have many different scripts for /// identifiers in the codebase. /// /// Note that if you only want to allow plain English, you might want to use @@ -27,9 +29,7 @@ declare_clippy_lint! { /// /// [`non_ascii_idents`]: https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html#non-ascii-idents /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// // Assuming that `clippy.toml` contains the following line: /// // allowed-locales = ["Latin", "Cyrillic"] diff --git a/clippy_lints/src/disallowed_type.rs b/clippy_lints/src/disallowed_type.rs index 7c76e2322c28f..e627168b93275 100644 --- a/clippy_lints/src/disallowed_type.rs +++ b/clippy_lints/src/disallowed_type.rs @@ -9,14 +9,13 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::{Span, Symbol}; declare_clippy_lint! { - /// **What it does:** Denies the configured types in clippy.toml. + /// ### What it does + /// Denies the configured types in clippy.toml. /// - /// **Why is this bad?** Some types are undesirable in certain contexts. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// Some types are undesirable in certain contexts. /// + /// ### Example: /// An example clippy.toml configuration: /// ```toml /// # clippy.toml diff --git a/clippy_lints/src/doc.rs b/clippy_lints/src/doc.rs index 0c19988a975a8..c39829fdc7aad 100644 --- a/clippy_lints/src/doc.rs +++ b/clippy_lints/src/doc.rs @@ -30,15 +30,18 @@ use std::thread; use url::Url; declare_clippy_lint! { - /// **What it does:** Checks for the presence of `_`, `::` or camel-case words + /// ### What it does + /// Checks for the presence of `_`, `::` or camel-case words /// outside ticks in documentation. /// - /// **Why is this bad?** *Rustdoc* supports markdown formatting, `_`, `::` and + /// ### Why is this bad? + /// *Rustdoc* supports markdown formatting, `_`, `::` and /// camel-case probably indicates some code which should be included between /// ticks. `_` can also be used for emphasis in markdown, this lint tries to /// consider that. /// - /// **Known problems:** Lots of bad docs won’t be fixed, what the lint checks + /// ### Known problems + /// Lots of bad docs won’t be fixed, what the lint checks /// for is limited, and there are still false positives. HTML elements and their /// content are not linted. /// @@ -47,7 +50,7 @@ declare_clippy_lint! { /// `[`SmallVec<[T; INLINE_CAPACITY]>`]` and then [`SmallVec<[T; INLINE_CAPACITY]>`]: SmallVec /// would fail. /// - /// **Examples:** + /// ### Examples /// ```rust /// /// Do something with the foo_bar parameter. See also /// /// that::other::module::foo. @@ -68,15 +71,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for the doc comments of publicly visible + /// ### What it does + /// Checks for the doc comments of publicly visible /// unsafe functions and warns if there is no `# Safety` section. /// - /// **Why is this bad?** Unsafe functions should document their safety + /// ### Why is this bad? + /// Unsafe functions should document their safety /// preconditions, so that users can be sure they are using them safely. /// - /// **Known problems:** None. - /// - /// **Examples:** + /// ### Examples /// ```rust ///# type Universe = (); /// /// This function should really be documented @@ -102,16 +105,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks the doc comments of publicly visible functions that + /// ### What it does + /// Checks the doc comments of publicly visible functions that /// return a `Result` type and warns if there is no `# Errors` section. /// - /// **Why is this bad?** Documenting the type of errors that can be returned from a + /// ### Why is this bad? + /// Documenting the type of errors that can be returned from a /// function can help callers write code to handle the errors appropriately. /// - /// **Known problems:** None. - /// - /// **Examples:** - /// + /// ### Examples /// Since the following function returns a `Result` it has an `# Errors` section in /// its doc comment: /// @@ -131,16 +133,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks the doc comments of publicly visible functions that + /// ### What it does + /// Checks the doc comments of publicly visible functions that /// may panic and warns if there is no `# Panics` section. /// - /// **Why is this bad?** Documenting the scenarios in which panicking occurs + /// ### Why is this bad? + /// Documenting the scenarios in which panicking occurs /// can help callers who do not want to panic to avoid those situations. /// - /// **Known problems:** None. - /// - /// **Examples:** - /// + /// ### Examples /// Since the following function may panic it has a `# Panics` section in /// its doc comment: /// @@ -162,14 +163,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `fn main() { .. }` in doctests + /// ### What it does + /// Checks for `fn main() { .. }` in doctests /// - /// **Why is this bad?** The test can be shorter (and likely more readable) + /// ### Why is this bad? + /// The test can be shorter (and likely more readable) /// if the `fn main()` is left implicit. /// - /// **Known problems:** None. - /// - /// **Examples:** + /// ### Examples /// ``````rust /// /// An example of a doctest with a `main()` function /// /// diff --git a/clippy_lints/src/double_comparison.rs b/clippy_lints/src/double_comparison.rs index 4966638cb1b96..6520bb91fafd2 100644 --- a/clippy_lints/src/double_comparison.rs +++ b/clippy_lints/src/double_comparison.rs @@ -10,14 +10,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::source_map::Span; declare_clippy_lint! { - /// **What it does:** Checks for double comparisons that could be simplified to a single expression. + /// ### What it does + /// Checks for double comparisons that could be simplified to a single expression. /// /// - /// **Why is this bad?** Readability. + /// ### Why is this bad? + /// Readability. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let x = 1; /// # let y = 2; diff --git a/clippy_lints/src/double_parens.rs b/clippy_lints/src/double_parens.rs index e4e4a93b011fd..d0d87b6df9a2d 100644 --- a/clippy_lints/src/double_parens.rs +++ b/clippy_lints/src/double_parens.rs @@ -4,14 +4,14 @@ use rustc_lint::{EarlyContext, EarlyLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for unnecessary double parentheses. + /// ### What it does + /// Checks for unnecessary double parentheses. /// - /// **Why is this bad?** This makes code harder to read and might indicate a + /// ### Why is this bad? + /// This makes code harder to read and might indicate a /// mistake. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// // Bad /// fn simple_double_parens() -> i32 { diff --git a/clippy_lints/src/drop_forget_ref.rs b/clippy_lints/src/drop_forget_ref.rs index b5b29760636ba..0f3dc866afb6e 100644 --- a/clippy_lints/src/drop_forget_ref.rs +++ b/clippy_lints/src/drop_forget_ref.rs @@ -8,17 +8,17 @@ use rustc_middle::ty; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for calls to `std::mem::drop` with a reference + /// ### What it does + /// Checks for calls to `std::mem::drop` with a reference /// instead of an owned value. /// - /// **Why is this bad?** Calling `drop` on a reference will only drop the + /// ### Why is this bad? + /// Calling `drop` on a reference will only drop the /// reference itself, which is a no-op. It will not call the `drop` method (from /// the `Drop` trait implementation) on the underlying referenced value, which /// is likely what was intended. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// let mut lock_guard = mutex.lock(); /// std::mem::drop(&lock_guard) // Should have been drop(lock_guard), mutex @@ -31,17 +31,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for calls to `std::mem::forget` with a reference + /// ### What it does + /// Checks for calls to `std::mem::forget` with a reference /// instead of an owned value. /// - /// **Why is this bad?** Calling `forget` on a reference will only forget the + /// ### Why is this bad? + /// Calling `forget` on a reference will only forget the /// reference itself, which is a no-op. It will not forget the underlying /// referenced /// value, which is likely what was intended. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x = Box::new(1); /// std::mem::forget(&x) // Should have been forget(x), x will still be dropped @@ -52,16 +52,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for calls to `std::mem::drop` with a value + /// ### What it does + /// Checks for calls to `std::mem::drop` with a value /// that derives the Copy trait /// - /// **Why is this bad?** Calling `std::mem::drop` [does nothing for types that + /// ### Why is this bad? + /// Calling `std::mem::drop` [does nothing for types that /// implement Copy](https://doc.rust-lang.org/std/mem/fn.drop.html), since the /// value will be copied and moved into the function on invocation. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x: i32 = 42; // i32 implements Copy /// std::mem::drop(x) // A copy of x is passed to the function, leaving the @@ -73,10 +73,12 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for calls to `std::mem::forget` with a value that + /// ### What it does + /// Checks for calls to `std::mem::forget` with a value that /// derives the Copy trait /// - /// **Why is this bad?** Calling `std::mem::forget` [does nothing for types that + /// ### Why is this bad? + /// Calling `std::mem::forget` [does nothing for types that /// implement Copy](https://doc.rust-lang.org/std/mem/fn.drop.html) since the /// value will be copied and moved into the function on invocation. /// @@ -86,9 +88,7 @@ declare_clippy_lint! { /// there /// is nothing for `std::mem::forget` to ignore. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x: i32 = 42; // i32 implements Copy /// std::mem::forget(x) // A copy of x is passed to the function, leaving the diff --git a/clippy_lints/src/duration_subsec.rs b/clippy_lints/src/duration_subsec.rs index 94b09bf717372..3774de625213d 100644 --- a/clippy_lints/src/duration_subsec.rs +++ b/clippy_lints/src/duration_subsec.rs @@ -12,15 +12,15 @@ use clippy_utils::diagnostics::span_lint_and_sugg; use clippy_utils::paths; declare_clippy_lint! { - /// **What it does:** Checks for calculation of subsecond microseconds or milliseconds + /// ### What it does + /// Checks for calculation of subsecond microseconds or milliseconds /// from other `Duration` methods. /// - /// **Why is this bad?** It's more concise to call `Duration::subsec_micros()` or + /// ### Why is this bad? + /// It's more concise to call `Duration::subsec_micros()` or /// `Duration::subsec_millis()` than to calculate them. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # use std::time::Duration; /// let dur = Duration::new(5, 0); diff --git a/clippy_lints/src/else_if_without_else.rs b/clippy_lints/src/else_if_without_else.rs index 26984df953977..0541ac5eccca4 100644 --- a/clippy_lints/src/else_if_without_else.rs +++ b/clippy_lints/src/else_if_without_else.rs @@ -7,14 +7,14 @@ use rustc_middle::lint::in_external_macro; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for usage of if expressions with an `else if` branch, + /// ### What it does + /// Checks for usage of if expressions with an `else if` branch, /// but without a final `else` branch. /// - /// **Why is this bad?** Some coding guidelines require this (e.g., MISRA-C:2004 Rule 14.10). + /// ### Why is this bad? + /// Some coding guidelines require this (e.g., MISRA-C:2004 Rule 14.10). /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # fn a() {} /// # fn b() {} diff --git a/clippy_lints/src/empty_enum.rs b/clippy_lints/src/empty_enum.rs index c92984a98346d..3453c2da2784f 100644 --- a/clippy_lints/src/empty_enum.rs +++ b/clippy_lints/src/empty_enum.rs @@ -6,13 +6,15 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for `enum`s with no variants. + /// ### What it does + /// Checks for `enum`s with no variants. /// /// As of this writing, the `never_type` is still a /// nightly-only experimental API. Therefore, this lint is only triggered /// if the `never_type` is enabled. /// - /// **Why is this bad?** If you want to introduce a type which + /// ### Why is this bad? + /// If you want to introduce a type which /// can't be instantiated, you should use `!` (the primitive type "never"), /// or a wrapper around it, because `!` has more extensive /// compiler support (type inference, etc...) and wrappers @@ -20,10 +22,7 @@ declare_clippy_lint! { /// For further information visit [never type documentation](https://doc.rust-lang.org/std/primitive.never.html) /// /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// Bad: /// ```rust /// enum Test {} diff --git a/clippy_lints/src/entry.rs b/clippy_lints/src/entry.rs index 2eb8b1422ed8a..e1d0d65edb1b9 100644 --- a/clippy_lints/src/entry.rs +++ b/clippy_lints/src/entry.rs @@ -16,12 +16,15 @@ use rustc_span::{Span, SyntaxContext, DUMMY_SP}; use std::fmt::Write; declare_clippy_lint! { - /// **What it does:** Checks for uses of `contains_key` + `insert` on `HashMap` + /// ### What it does + /// Checks for uses of `contains_key` + `insert` on `HashMap` /// or `BTreeMap`. /// - /// **Why is this bad?** Using `entry` is more efficient. + /// ### Why is this bad? + /// Using `entry` is more efficient. /// - /// **Known problems:** The suggestion may have type inference errors in some cases. e.g. + /// ### Known problems + /// The suggestion may have type inference errors in some cases. e.g. /// ```rust /// let mut map = std::collections::HashMap::new(); /// let _ = if !map.contains_key(&0) { @@ -31,7 +34,7 @@ declare_clippy_lint! { /// }; /// ``` /// - /// **Example:** + /// ### Example /// ```rust /// # use std::collections::HashMap; /// # let mut map = HashMap::new(); diff --git a/clippy_lints/src/enum_clike.rs b/clippy_lints/src/enum_clike.rs index 021136ac5e019..a2c3c7a7b4920 100644 --- a/clippy_lints/src/enum_clike.rs +++ b/clippy_lints/src/enum_clike.rs @@ -11,15 +11,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use std::convert::TryFrom; declare_clippy_lint! { - /// **What it does:** Checks for C-like enumerations that are + /// ### What it does + /// Checks for C-like enumerations that are /// `repr(isize/usize)` and have values that don't fit into an `i32`. /// - /// **Why is this bad?** This will truncate the variant value on 32 bit + /// ### Why is this bad? + /// This will truncate the variant value on 32 bit /// architectures, but works fine on 64 bit. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # #[cfg(target_pointer_width = "64")] /// #[repr(usize)] diff --git a/clippy_lints/src/enum_variants.rs b/clippy_lints/src/enum_variants.rs index b1a105a51c106..32b95745b64d1 100644 --- a/clippy_lints/src/enum_variants.rs +++ b/clippy_lints/src/enum_variants.rs @@ -10,15 +10,15 @@ use rustc_span::source_map::Span; use rustc_span::symbol::Symbol; declare_clippy_lint! { - /// **What it does:** Detects enumeration variants that are prefixed or suffixed + /// ### What it does + /// Detects enumeration variants that are prefixed or suffixed /// by the same characters. /// - /// **Why is this bad?** Enumeration variant names should specify their variant, + /// ### Why is this bad? + /// Enumeration variant names should specify their variant, /// not repeat the enumeration name. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// enum Cake { /// BlackForestCake, @@ -40,14 +40,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Detects type names that are prefixed or suffixed by the + /// ### What it does + /// Detects type names that are prefixed or suffixed by the /// containing module's name. /// - /// **Why is this bad?** It requires the user to type the module name twice. - /// - /// **Known problems:** None. + /// ### Why is this bad? + /// It requires the user to type the module name twice. /// - /// **Example:** + /// ### Example /// ```rust /// mod cake { /// struct BlackForestCake; @@ -65,10 +65,12 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for modules that have the same name as their + /// ### What it does + /// Checks for modules that have the same name as their /// parent module /// - /// **Why is this bad?** A typical beginner mistake is to have `mod foo;` and + /// ### Why is this bad? + /// A typical beginner mistake is to have `mod foo;` and /// again `mod foo { .. /// }` in `foo.rs`. /// The expectation is that items inside the inner `mod foo { .. }` are then @@ -78,9 +80,7 @@ declare_clippy_lint! { /// If this is done on purpose, it would be better to choose a more /// representative module name. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// // lib.rs /// mod foo; diff --git a/clippy_lints/src/eq_op.rs b/clippy_lints/src/eq_op.rs index d39cabfb2825b..51d5094e8c998 100644 --- a/clippy_lints/src/eq_op.rs +++ b/clippy_lints/src/eq_op.rs @@ -9,18 +9,21 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for equal operands to comparison, logical and + /// ### What it does + /// Checks for equal operands to comparison, logical and /// bitwise, difference and division binary operators (`==`, `>`, etc., `&&`, /// `||`, `&`, `|`, `^`, `-` and `/`). /// - /// **Why is this bad?** This is usually just a typo or a copy and paste error. + /// ### Why is this bad? + /// This is usually just a typo or a copy and paste error. /// - /// **Known problems:** False negatives: We had some false positives regarding + /// ### Known problems + /// False negatives: We had some false positives regarding /// calls (notably [racer](https://github.com/phildawes/racer) had one instance /// of `x.pop() && x.pop()`), so we removed matching any function or method /// calls. We may introduce a list of known pure functions in the future. /// - /// **Example:** + /// ### Example /// ```rust /// # let x = 1; /// if x + 1 == x + 1 {} @@ -37,15 +40,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for arguments to `==` which have their address + /// ### What it does + /// Checks for arguments to `==` which have their address /// taken to satisfy a bound /// and suggests to dereference the other argument instead /// - /// **Why is this bad?** It is more idiomatic to dereference the other argument. + /// ### Why is this bad? + /// It is more idiomatic to dereference the other argument. /// - /// **Known problems:** None + /// ### Known problems + /// None /// - /// **Example:** + /// ### Example /// ```ignore /// // Bad /// &x == y diff --git a/clippy_lints/src/erasing_op.rs b/clippy_lints/src/erasing_op.rs index 4aa9c25b1b0b0..026d14d0ea265 100644 --- a/clippy_lints/src/erasing_op.rs +++ b/clippy_lints/src/erasing_op.rs @@ -6,15 +6,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::source_map::Span; declare_clippy_lint! { - /// **What it does:** Checks for erasing operations, e.g., `x * 0`. + /// ### What it does + /// Checks for erasing operations, e.g., `x * 0`. /// - /// **Why is this bad?** The whole expression can be replaced by zero. + /// ### Why is this bad? + /// The whole expression can be replaced by zero. /// This is most likely not the intended outcome and should probably be /// corrected /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x = 1; /// 0 / x; diff --git a/clippy_lints/src/escape.rs b/clippy_lints/src/escape.rs index 5f400d079da2f..8b0e9e6bc9b93 100644 --- a/clippy_lints/src/escape.rs +++ b/clippy_lints/src/escape.rs @@ -19,16 +19,16 @@ pub struct BoxedLocal { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `Box<T>` where an unboxed `T` would + /// ### What it does + /// Checks for usage of `Box<T>` where an unboxed `T` would /// work fine. /// - /// **Why is this bad?** This is an unnecessary allocation, and bad for + /// ### Why is this bad? + /// This is an unnecessary allocation, and bad for /// performance. It is only necessary to allocate if you wish to move the box /// into something. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # fn foo(bar: usize) {} /// // Bad diff --git a/clippy_lints/src/eta_reduction.rs b/clippy_lints/src/eta_reduction.rs index 667eb8eb283bb..192b69e18f90f 100644 --- a/clippy_lints/src/eta_reduction.rs +++ b/clippy_lints/src/eta_reduction.rs @@ -14,19 +14,22 @@ use rustc_middle::ty::{self, ClosureKind, Ty}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for closures which just call another function where + /// ### What it does + /// Checks for closures which just call another function where /// the function can be called directly. `unsafe` functions or calls where types /// get adjusted are ignored. /// - /// **Why is this bad?** Needlessly creating a closure adds code for no benefit + /// ### Why is this bad? + /// Needlessly creating a closure adds code for no benefit /// and gives the optimizer more work. /// - /// **Known problems:** If creating the closure inside the closure has a side- + /// ### Known problems + /// If creating the closure inside the closure has a side- /// effect then moving the closure creation out will change when that side- /// effect runs. /// See [#1439](https://github.com/rust-lang/rust-clippy/issues/1439) for more details. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// // Bad /// xs.map(|x| foo(x)) @@ -42,17 +45,20 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for closures which only invoke a method on the closure + /// ### What it does + /// Checks for closures which only invoke a method on the closure /// argument and can be replaced by referencing the method directly. /// - /// **Why is this bad?** It's unnecessary to create the closure. + /// ### Why is this bad? + /// It's unnecessary to create the closure. /// - /// **Known problems:** [#3071](https://github.com/rust-lang/rust-clippy/issues/3071), + /// ### Known problems + /// [#3071](https://github.com/rust-lang/rust-clippy/issues/3071), /// [#3942](https://github.com/rust-lang/rust-clippy/issues/3942), /// [#4002](https://github.com/rust-lang/rust-clippy/issues/4002) /// /// - /// **Example:** + /// ### Example /// ```rust,ignore /// Some('a').map(|s| s.to_uppercase()); /// ``` diff --git a/clippy_lints/src/eval_order_dependence.rs b/clippy_lints/src/eval_order_dependence.rs index 03a8b40df555f..f72a1e446d55c 100644 --- a/clippy_lints/src/eval_order_dependence.rs +++ b/clippy_lints/src/eval_order_dependence.rs @@ -9,17 +9,20 @@ use rustc_middle::ty; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for a read and a write to the same variable where + /// ### What it does + /// Checks for a read and a write to the same variable where /// whether the read occurs before or after the write depends on the evaluation /// order of sub-expressions. /// - /// **Why is this bad?** It is often confusing to read. In addition, the + /// ### Why is this bad? + /// It is often confusing to read. In addition, the /// sub-expression evaluation order for Rust is not well documented. /// - /// **Known problems:** Code which intentionally depends on the evaluation + /// ### Known problems + /// Code which intentionally depends on the evaluation /// order, or which is correct for any evaluation order. /// - /// **Example:** + /// ### Example /// ```rust /// let mut x = 0; /// @@ -43,16 +46,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for diverging calls that are not match arms or + /// ### What it does + /// Checks for diverging calls that are not match arms or /// statements. /// - /// **Why is this bad?** It is often confusing to read. In addition, the + /// ### Why is this bad? + /// It is often confusing to read. In addition, the /// sub-expression evaluation order for Rust is not well documented. /// - /// **Known problems:** Someone might want to use `some_bool || panic!()` as a + /// ### Known problems + /// Someone might want to use `some_bool || panic!()` as a /// shorthand. /// - /// **Example:** + /// ### Example /// ```rust,no_run /// # fn b() -> bool { true } /// # fn c() -> bool { true } diff --git a/clippy_lints/src/excessive_bools.rs b/clippy_lints/src/excessive_bools.rs index 4e2dbf005d51c..476e6d23f1215 100644 --- a/clippy_lints/src/excessive_bools.rs +++ b/clippy_lints/src/excessive_bools.rs @@ -8,19 +8,19 @@ use rustc_span::{sym, Span}; use std::convert::TryInto; declare_clippy_lint! { - /// **What it does:** Checks for excessive + /// ### What it does + /// Checks for excessive /// use of bools in structs. /// - /// **Why is this bad?** Excessive bools in a struct + /// ### Why is this bad? + /// Excessive bools in a struct /// is often a sign that it's used as a state machine, /// which is much better implemented as an enum. /// If it's not the case, excessive bools usually benefit /// from refactoring into two-variant enums for better /// readability and API. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// Bad: /// ```rust /// struct S { @@ -44,19 +44,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for excessive use of + /// ### What it does + /// Checks for excessive use of /// bools in function definitions. /// - /// **Why is this bad?** Calls to such functions + /// ### Why is this bad? + /// Calls to such functions /// are confusing and error prone, because it's /// hard to remember argument order and you have /// no type system support to back you up. Using /// two-variant enums instead of bools often makes /// API easier to use. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// Bad: /// ```rust,ignore /// fn f(is_round: bool, is_hot: bool) { ... } diff --git a/clippy_lints/src/exhaustive_items.rs b/clippy_lints/src/exhaustive_items.rs index 60ad2e8ee1404..e00126046c022 100644 --- a/clippy_lints/src/exhaustive_items.rs +++ b/clippy_lints/src/exhaustive_items.rs @@ -8,16 +8,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Warns on any exported `enum`s that are not tagged `#[non_exhaustive]` + /// ### What it does + /// Warns on any exported `enum`s that are not tagged `#[non_exhaustive]` /// - /// **Why is this bad?** Exhaustive enums are typically fine, but a project which does + /// ### Why is this bad? + /// Exhaustive enums are typically fine, but a project which does /// not wish to make a stability commitment around exported enums may wish to /// disable them by default. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// enum Foo { /// Bar, @@ -38,16 +37,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Warns on any exported `structs`s that are not tagged `#[non_exhaustive]` + /// ### What it does + /// Warns on any exported `structs`s that are not tagged `#[non_exhaustive]` /// - /// **Why is this bad?** Exhaustive structs are typically fine, but a project which does + /// ### Why is this bad? + /// Exhaustive structs are typically fine, but a project which does /// not wish to make a stability commitment around exported structs may wish to /// disable them by default. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// struct Foo { /// bar: u8, diff --git a/clippy_lints/src/exit.rs b/clippy_lints/src/exit.rs index 16246e548b613..9cd5b2d9f4439 100644 --- a/clippy_lints/src/exit.rs +++ b/clippy_lints/src/exit.rs @@ -6,15 +6,15 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** `exit()` terminates the program and doesn't provide a + /// ### What it does + /// `exit()` terminates the program and doesn't provide a /// stack trace. /// - /// **Why is this bad?** Ideally a program is terminated by finishing + /// ### Why is this bad? + /// Ideally a program is terminated by finishing /// the main function. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// std::process::exit(0) /// ``` diff --git a/clippy_lints/src/explicit_write.rs b/clippy_lints/src/explicit_write.rs index 66724294804a8..4f46ef906f409 100644 --- a/clippy_lints/src/explicit_write.rs +++ b/clippy_lints/src/explicit_write.rs @@ -9,14 +9,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for usage of `write!()` / `writeln()!` which can be + /// ### What it does + /// Checks for usage of `write!()` / `writeln()!` which can be /// replaced with `(e)print!()` / `(e)println!()` /// - /// **Why is this bad?** Using `(e)println! is clearer and more concise + /// ### Why is this bad? + /// Using `(e)println! is clearer and more concise /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # use std::io::Write; /// # let bar = "furchtbar"; diff --git a/clippy_lints/src/fallible_impl_from.rs b/clippy_lints/src/fallible_impl_from.rs index 2937fcb9ca0f3..7e4d1b3ef9f0d 100644 --- a/clippy_lints/src/fallible_impl_from.rs +++ b/clippy_lints/src/fallible_impl_from.rs @@ -10,13 +10,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::{sym, Span}; declare_clippy_lint! { - /// **What it does:** Checks for impls of `From<..>` that contain `panic!()` or `unwrap()` + /// ### What it does + /// Checks for impls of `From<..>` that contain `panic!()` or `unwrap()` /// - /// **Why is this bad?** `TryFrom` should be used if there's a possibility of failure. + /// ### Why is this bad? + /// `TryFrom` should be used if there's a possibility of failure. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// struct Foo(i32); /// diff --git a/clippy_lints/src/float_equality_without_abs.rs b/clippy_lints/src/float_equality_without_abs.rs index 1e503cc795ccb..c33d80b8e8ef9 100644 --- a/clippy_lints/src/float_equality_without_abs.rs +++ b/clippy_lints/src/float_equality_without_abs.rs @@ -11,30 +11,32 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::source_map::Spanned; declare_clippy_lint! { - /// **What it does:** Checks for statements of the form `(a - b) < f32::EPSILON` or - /// `(a - b) < f64::EPSILON`. Notes the missing `.abs()`. - /// - /// **Why is this bad?** The code without `.abs()` is more likely to have a bug. - /// - /// **Known problems:** If the user can ensure that b is larger than a, the `.abs()` is - /// technically unneccessary. However, it will make the code more robust and doesn't have any - /// large performance implications. If the abs call was deliberately left out for performance - /// reasons, it is probably better to state this explicitly in the code, which then can be done - /// with an allow. - /// - /// **Example:** - /// - /// ```rust - /// pub fn is_roughly_equal(a: f32, b: f32) -> bool { - /// (a - b) < f32::EPSILON - /// } - /// ``` - /// Use instead: - /// ```rust - /// pub fn is_roughly_equal(a: f32, b: f32) -> bool { - /// (a - b).abs() < f32::EPSILON - /// } - /// ``` + /// ### What it does + /// Checks for statements of the form `(a - b) < f32::EPSILON` or + /// `(a - b) < f64::EPSILON`. Notes the missing `.abs()`. + /// + /// ### Why is this bad? + /// The code without `.abs()` is more likely to have a bug. + /// + /// ### Known problems + /// If the user can ensure that b is larger than a, the `.abs()` is + /// technically unneccessary. However, it will make the code more robust and doesn't have any + /// large performance implications. If the abs call was deliberately left out for performance + /// reasons, it is probably better to state this explicitly in the code, which then can be done + /// with an allow. + /// + /// ### Example + /// ```rust + /// pub fn is_roughly_equal(a: f32, b: f32) -> bool { + /// (a - b) < f32::EPSILON + /// } + /// ``` + /// Use instead: + /// ```rust + /// pub fn is_roughly_equal(a: f32, b: f32) -> bool { + /// (a - b).abs() < f32::EPSILON + /// } + /// ``` pub FLOAT_EQUALITY_WITHOUT_ABS, suspicious, "float equality check without `.abs()`" diff --git a/clippy_lints/src/float_literal.rs b/clippy_lints/src/float_literal.rs index 7968e7b764df3..a3d70f31f0021 100644 --- a/clippy_lints/src/float_literal.rs +++ b/clippy_lints/src/float_literal.rs @@ -10,15 +10,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use std::fmt; declare_clippy_lint! { - /// **What it does:** Checks for float literals with a precision greater + /// ### What it does + /// Checks for float literals with a precision greater /// than that supported by the underlying type. /// - /// **Why is this bad?** Rust will truncate the literal silently. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// Rust will truncate the literal silently. /// + /// ### Example /// ```rust /// // Bad /// let v: f32 = 0.123_456_789_9; @@ -34,16 +33,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for whole number float literals that + /// ### What it does + /// Checks for whole number float literals that /// cannot be represented as the underlying type without loss. /// - /// **Why is this bad?** Rust will silently lose precision during + /// ### Why is this bad? + /// Rust will silently lose precision during /// conversion to a float. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// // Bad /// let _: f32 = 16_777_217.0; // 16_777_216.0 diff --git a/clippy_lints/src/floating_point_arithmetic.rs b/clippy_lints/src/floating_point_arithmetic.rs index e38384b01d414..b01c0cdd84624 100644 --- a/clippy_lints/src/floating_point_arithmetic.rs +++ b/clippy_lints/src/floating_point_arithmetic.rs @@ -18,16 +18,15 @@ use std::f64::consts as f64_consts; use sugg::Sugg; declare_clippy_lint! { - /// **What it does:** Looks for floating-point expressions that + /// ### What it does + /// Looks for floating-point expressions that /// can be expressed using built-in methods to improve accuracy /// at the cost of performance. /// - /// **Why is this bad?** Negatively impacts accuracy. - /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Why is this bad? + /// Negatively impacts accuracy. /// + /// ### Example /// ```rust /// let a = 3f32; /// let _ = a.powf(1.0 / 3.0); @@ -49,16 +48,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Looks for floating-point expressions that + /// ### What it does + /// Looks for floating-point expressions that /// can be expressed using built-in methods to improve both /// accuracy and performance. /// - /// **Why is this bad?** Negatively impacts accuracy and performance. - /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Why is this bad? + /// Negatively impacts accuracy and performance. /// + /// ### Example /// ```rust /// use std::f32::consts::E; /// diff --git a/clippy_lints/src/format.rs b/clippy_lints/src/format.rs index ca3490d8edad9..863c606f5a92c 100644 --- a/clippy_lints/src/format.rs +++ b/clippy_lints/src/format.rs @@ -13,18 +13,18 @@ use rustc_span::symbol::kw; use rustc_span::{sym, Span}; declare_clippy_lint! { - /// **What it does:** Checks for the use of `format!("string literal with no + /// ### What it does + /// Checks for the use of `format!("string literal with no /// argument")` and `format!("{}", foo)` where `foo` is a string. /// - /// **Why is this bad?** There is no point of doing that. `format!("foo")` can + /// ### Why is this bad? + /// There is no point of doing that. `format!("foo")` can /// be replaced by `"foo".to_owned()` if you really need a `String`. The even /// worse `&format!("foo")` is often encountered in the wild. `format!("{}", /// foo)` can be replaced by `foo.clone()` if `foo: String` or `foo.to_owned()` /// if `foo: &str`. /// - /// **Known problems:** None. - /// - /// **Examples:** + /// ### Examples /// ```rust /// /// // Bad diff --git a/clippy_lints/src/formatting.rs b/clippy_lints/src/formatting.rs index 8aefb8d46f6e8..b4cf1971d78dc 100644 --- a/clippy_lints/src/formatting.rs +++ b/clippy_lints/src/formatting.rs @@ -9,15 +9,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::source_map::Span; declare_clippy_lint! { - /// **What it does:** Checks for use of the non-existent `=*`, `=!` and `=-` + /// ### What it does + /// Checks for use of the non-existent `=*`, `=!` and `=-` /// operators. /// - /// **Why is this bad?** This is either a typo of `*=`, `!=` or `-=` or + /// ### Why is this bad? + /// This is either a typo of `*=`, `!=` or `-=` or /// confusing. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// a =- 42; // confusing, should it be `a -= 42` or `a = -42`? /// ``` @@ -27,15 +27,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks the formatting of a unary operator on the right hand side + /// ### What it does + /// Checks the formatting of a unary operator on the right hand side /// of a binary operator. It lints if there is no space between the binary and unary operators, /// but there is a space between the unary and its operand. /// - /// **Why is this bad?** This is either a typo in the binary operator or confusing. - /// - /// **Known problems:** None. + /// ### Why is this bad? + /// This is either a typo in the binary operator or confusing. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// if foo <- 30 { // this should be `foo < -30` but looks like a different operator /// } @@ -49,15 +49,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for formatting of `else`. It lints if the `else` + /// ### What it does + /// Checks for formatting of `else`. It lints if the `else` /// is followed immediately by a newline or the `else` seems to be missing. /// - /// **Why is this bad?** This is probably some refactoring remnant, even if the + /// ### Why is this bad? + /// This is probably some refactoring remnant, even if the /// code is correct, it might look confusing. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// if foo { /// } { // looks like an `else` is missing here @@ -85,14 +85,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for possible missing comma in an array. It lints if + /// ### What it does + /// Checks for possible missing comma in an array. It lints if /// an array element is a binary operator expression and it lies on two lines. /// - /// **Why is this bad?** This could lead to unexpected results. - /// - /// **Known problems:** None. + /// ### Why is this bad? + /// This could lead to unexpected results. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// let a = &[ /// -1, -2, -3 // <= no comma here diff --git a/clippy_lints/src/from_over_into.rs b/clippy_lints/src/from_over_into.rs index 48316c3a61df0..623546cd1dea9 100644 --- a/clippy_lints/src/from_over_into.rs +++ b/clippy_lints/src/from_over_into.rs @@ -8,14 +8,13 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::symbol::sym; declare_clippy_lint! { - /// **What it does:** Searches for implementations of the `Into<..>` trait and suggests to implement `From<..>` instead. + /// ### What it does + /// Searches for implementations of the `Into<..>` trait and suggests to implement `From<..>` instead. /// - /// **Why is this bad?** According the std docs implementing `From<..>` is preferred since it gives you `Into<..>` for free where the reverse isn't true. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// According the std docs implementing `From<..>` is preferred since it gives you `Into<..>` for free where the reverse isn't true. /// + /// ### Example /// ```rust /// struct StringWrapper(String); /// diff --git a/clippy_lints/src/from_str_radix_10.rs b/clippy_lints/src/from_str_radix_10.rs index 3da5bc95b6db1..cc4bb85c50f7e 100644 --- a/clippy_lints/src/from_str_radix_10.rs +++ b/clippy_lints/src/from_str_radix_10.rs @@ -10,20 +10,22 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::symbol::sym; declare_clippy_lint! { - /// **What it does:** + /// ### What it does + /// /// Checks for function invocations of the form `primitive::from_str_radix(s, 10)` /// - /// **Why is this bad?** + /// ### Why is this bad? + /// /// This specific common use case can be rewritten as `s.parse::<primitive>()` /// (and in most cases, the turbofish can be removed), which reduces code length /// and complexity. /// - /// **Known problems:** + /// ### Known problems + /// /// This lint may suggest using (&<expression>).parse() instead of <expression>.parse() directly /// in some cases, which is correct but adds unnecessary complexity to the code. /// - /// **Example:** - /// + /// ### Example /// ```ignore /// let input: &str = get_input(); /// let num = u16::from_str_radix(input, 10)?; diff --git a/clippy_lints/src/functions/mod.rs b/clippy_lints/src/functions/mod.rs index 2beb9bc94bf06..ce23c0ce4a076 100644 --- a/clippy_lints/src/functions/mod.rs +++ b/clippy_lints/src/functions/mod.rs @@ -11,15 +11,15 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** Checks for functions with too many parameters. + /// ### What it does + /// Checks for functions with too many parameters. /// - /// **Why is this bad?** Functions with lots of parameters are considered bad + /// ### Why is this bad? + /// Functions with lots of parameters are considered bad /// style and reduce readability (“what does the 5th parameter mean?”). Consider /// grouping some parameters into a new type. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # struct Color; /// fn foo(x: u32, y: u32, name: &str, c: Color, w: f32, h: f32, a: f32, b: f32) { @@ -32,16 +32,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for functions with a large amount of lines. + /// ### What it does + /// Checks for functions with a large amount of lines. /// - /// **Why is this bad?** Functions with a lot of lines are harder to understand + /// ### Why is this bad? + /// Functions with a lot of lines are harder to understand /// due to having to look at a larger amount of code to understand what the /// function is doing. Consider splitting the body of the function into /// multiple functions. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// fn im_too_long() { /// println!(""); @@ -55,15 +55,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for public functions that dereference raw pointer + /// ### What it does + /// Checks for public functions that dereference raw pointer /// arguments but are not marked `unsafe`. /// - /// **Why is this bad?** The function should probably be marked `unsafe`, since + /// ### Why is this bad? + /// The function should probably be marked `unsafe`, since /// for an arbitrary raw pointer, there is no way of telling for sure if it is /// valid. /// - /// **Known problems:** - /// + /// ### Known problems /// * It does not check functions recursively so if the pointer is passed to a /// private non-`unsafe` function which does the dereferencing, the lint won't /// trigger. @@ -71,7 +72,7 @@ declare_clippy_lint! { /// got from an argument in some other way (`fn foo(bar: &[*const u8])` or /// `some_argument.get_raw_ptr()`). /// - /// **Example:** + /// ### Example /// ```rust,ignore /// // Bad /// pub fn foo(x: *const u8) { @@ -89,17 +90,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for a [`#[must_use]`] attribute on + /// ### What it does + /// Checks for a [`#[must_use]`] attribute on /// unit-returning functions and methods. /// /// [`#[must_use]`]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-must_use-attribute /// - /// **Why is this bad?** Unit values are useless. The attribute is likely + /// ### Why is this bad? + /// Unit values are useless. The attribute is likely /// a remnant of a refactoring that removed the return type. /// - /// **Known problems:** None. - /// - /// **Examples:** + /// ### Examples /// ```rust /// #[must_use] /// fn useless() { } @@ -110,19 +111,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for a [`#[must_use]`] attribute without + /// ### What it does + /// Checks for a [`#[must_use]`] attribute without /// further information on functions and methods that return a type already /// marked as `#[must_use]`. /// /// [`#[must_use]`]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-must_use-attribute /// - /// **Why is this bad?** The attribute isn't needed. Not using the result + /// ### Why is this bad? + /// The attribute isn't needed. Not using the result /// will already be reported. Alternatively, one can add some text to the /// attribute to improve the lint message. /// - /// **Known problems:** None. - /// - /// **Examples:** + /// ### Examples /// ```rust /// #[must_use] /// fn double_must_use() -> Result<(), ()> { @@ -135,16 +136,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for public functions that have no + /// ### What it does + /// Checks for public functions that have no /// [`#[must_use]`] attribute, but return something not already marked /// must-use, have no mutable arg and mutate no statics. /// /// [`#[must_use]`]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-must_use-attribute /// - /// **Why is this bad?** Not bad at all, this lint just shows places where + /// ### Why is this bad? + /// Not bad at all, this lint just shows places where /// you could add the attribute. /// - /// **Known problems:** The lint only checks the arguments for mutable + /// ### Known problems + /// The lint only checks the arguments for mutable /// types without looking if they are actually changed. On the other hand, /// it also ignores a broad range of potentially interesting side effects, /// because we cannot decide whether the programmer intends the function to @@ -152,7 +156,7 @@ declare_clippy_lint! { /// positives. At least we don't lint if the result type is unit or already /// `#[must_use]`. /// - /// **Examples:** + /// ### Examples /// ```rust /// // this could be annotated with `#[must_use]`. /// fn id<T>(t: T) -> T { t } @@ -163,20 +167,23 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for public functions that return a `Result` + /// ### What it does + /// Checks for public functions that return a `Result` /// with an `Err` type of `()`. It suggests using a custom type that /// implements `std::error::Error`. /// - /// **Why is this bad?** Unit does not implement `Error` and carries no + /// ### Why is this bad? + /// Unit does not implement `Error` and carries no /// further information about what went wrong. /// - /// **Known problems:** Of course, this lint assumes that `Result` is used + /// ### Known problems + /// Of course, this lint assumes that `Result` is used /// for a fallible operation (which is after all the intended use). However /// code may opt to (mis)use it as a basic two-variant-enum. In that case, /// the suggestion is misguided, and the code should use a custom enum /// instead. /// - /// **Examples:** + /// ### Examples /// ```rust /// pub fn read_u8() -> Result<u8, ()> { Err(()) } /// ``` diff --git a/clippy_lints/src/future_not_send.rs b/clippy_lints/src/future_not_send.rs index 515b8887453b9..0be03969bcbe2 100644 --- a/clippy_lints/src/future_not_send.rs +++ b/clippy_lints/src/future_not_send.rs @@ -12,12 +12,14 @@ use rustc_trait_selection::traits::error_reporting::suggestions::InferCtxtExt; use rustc_trait_selection::traits::{self, FulfillmentError, TraitEngine}; declare_clippy_lint! { - /// **What it does:** This lint requires Future implementations returned from + /// ### What it does + /// This lint requires Future implementations returned from /// functions and methods to implement the `Send` marker trait. It is mostly /// used by library authors (public and internal) that target an audience where /// multithreaded executors are likely to be used for running these Futures. /// - /// **Why is this bad?** A Future implementation captures some state that it + /// ### Why is this bad? + /// A Future implementation captures some state that it /// needs to eventually produce its final value. When targeting a multithreaded /// executor (which is the norm on non-embedded devices) this means that this /// state may need to be transported to other threads, in other words the @@ -31,10 +33,7 @@ declare_clippy_lint! { /// modifying the library where the offending Future implementation is /// produced. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// async fn not_send(bytes: std::rc::Rc<[u8]>) {} /// ``` diff --git a/clippy_lints/src/get_last_with_len.rs b/clippy_lints/src/get_last_with_len.rs index 8e45fdfecc447..ced35030de835 100644 --- a/clippy_lints/src/get_last_with_len.rs +++ b/clippy_lints/src/get_last_with_len.rs @@ -14,10 +14,12 @@ use rustc_span::source_map::Spanned; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for using `x.get(x.len() - 1)` instead of + /// ### What it does + /// Checks for using `x.get(x.len() - 1)` instead of /// `x.last()`. /// - /// **Why is this bad?** Using `x.last()` is easier to read and has the same + /// ### Why is this bad? + /// Using `x.last()` is easier to read and has the same /// result. /// /// Note that using `x[x.len() - 1]` is semantically different from @@ -27,10 +29,7 @@ declare_clippy_lint! { /// There is another lint (get_unwrap) that covers the case of using /// `x.get(index).unwrap()` instead of `x[index]`. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// // Bad /// let x = vec![2, 3, 5]; diff --git a/clippy_lints/src/identity_op.rs b/clippy_lints/src/identity_op.rs index 99c461930e4c1..5feb0ce8dece7 100644 --- a/clippy_lints/src/identity_op.rs +++ b/clippy_lints/src/identity_op.rs @@ -11,14 +11,14 @@ use clippy_utils::diagnostics::span_lint; use clippy_utils::{clip, unsext}; declare_clippy_lint! { - /// **What it does:** Checks for identity operations, e.g., `x + 0`. + /// ### What it does + /// Checks for identity operations, e.g., `x + 0`. /// - /// **Why is this bad?** This code can be removed without changing the + /// ### Why is this bad? + /// This code can be removed without changing the /// meaning. So it just obscures what's going on. Delete it mercilessly. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let x = 1; /// x / 1 + 0 * 1 - 0 | 0; diff --git a/clippy_lints/src/if_let_mutex.rs b/clippy_lints/src/if_let_mutex.rs index 5403d76ea30c8..d3ddeda9fd1b9 100644 --- a/clippy_lints/src/if_let_mutex.rs +++ b/clippy_lints/src/if_let_mutex.rs @@ -9,16 +9,15 @@ use rustc_middle::hir::map::Map; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for `Mutex::lock` calls in `if let` expression + /// ### What it does + /// Checks for `Mutex::lock` calls in `if let` expression /// with lock calls in any of the else blocks. /// - /// **Why is this bad?** The Mutex lock remains held for the whole + /// ### Why is this bad? + /// The Mutex lock remains held for the whole /// `if let ... else` block and deadlocks. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust,ignore /// if let Ok(thing) = mutex.lock() { /// do_thing(); diff --git a/clippy_lints/src/if_let_some_result.rs b/clippy_lints/src/if_let_some_result.rs index 611da3744eeee..587307811a113 100644 --- a/clippy_lints/src/if_let_some_result.rs +++ b/clippy_lints/src/if_let_some_result.rs @@ -10,14 +10,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:*** Checks for unnecessary `ok()` in if let. + /// ### What it does + ///* Checks for unnecessary `ok()` in if let. /// - /// **Why is this bad?** Calling `ok()` in if let is unnecessary, instead match + /// ### Why is this bad? + /// Calling `ok()` in if let is unnecessary, instead match /// on `Ok(pat)` /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// for i in iter { /// if let Some(value) = i.parse().ok() { diff --git a/clippy_lints/src/if_not_else.rs b/clippy_lints/src/if_not_else.rs index c56f67df0618f..28db7233d70e8 100644 --- a/clippy_lints/src/if_not_else.rs +++ b/clippy_lints/src/if_not_else.rs @@ -8,14 +8,14 @@ use rustc_middle::lint::in_external_macro; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for usage of `!` or `!=` in an if condition with an + /// ### What it does + /// Checks for usage of `!` or `!=` in an if condition with an /// else branch. /// - /// **Why is this bad?** Negations reduce the readability of statements. + /// ### Why is this bad? + /// Negations reduce the readability of statements. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let v: Vec<usize> = vec![]; /// # fn a() {} diff --git a/clippy_lints/src/if_then_some_else_none.rs b/clippy_lints/src/if_then_some_else_none.rs index eadcd0867a880..17b9a2f888e0d 100644 --- a/clippy_lints/src/if_then_some_else_none.rs +++ b/clippy_lints/src/if_then_some_else_none.rs @@ -10,14 +10,13 @@ use rustc_semver::RustcVersion; use rustc_session::{declare_tool_lint, impl_lint_pass}; declare_clippy_lint! { - /// **What it does:** Checks for if-else that could be written to `bool::then`. + /// ### What it does + /// Checks for if-else that could be written to `bool::then`. /// - /// **Why is this bad?** Looks a little redundant. Using `bool::then` helps it have less lines of code. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// Looks a little redundant. Using `bool::then` helps it have less lines of code. /// + /// ### Example /// ```rust /// # let v = vec![0]; /// let a = if v.is_empty() { diff --git a/clippy_lints/src/implicit_hasher.rs b/clippy_lints/src/implicit_hasher.rs index 879d6a75bbedd..aae44f64e6695 100644 --- a/clippy_lints/src/implicit_hasher.rs +++ b/clippy_lints/src/implicit_hasher.rs @@ -22,18 +22,21 @@ use clippy_utils::source::{snippet, snippet_opt}; use clippy_utils::ty::is_type_diagnostic_item; declare_clippy_lint! { - /// **What it does:** Checks for public `impl` or `fn` missing generalization + /// ### What it does + /// Checks for public `impl` or `fn` missing generalization /// over different hashers and implicitly defaulting to the default hashing /// algorithm (`SipHash`). /// - /// **Why is this bad?** `HashMap` or `HashSet` with custom hashers cannot be + /// ### Why is this bad? + /// `HashMap` or `HashSet` with custom hashers cannot be /// used with them. /// - /// **Known problems:** Suggestions for replacing constructors can contain + /// ### Known problems + /// Suggestions for replacing constructors can contain /// false-positives. Also applying suggestions can require modification of other /// pieces of code, possibly including external crates. /// - /// **Example:** + /// ### Example /// ```rust /// # use std::collections::HashMap; /// # use std::hash::{Hash, BuildHasher}; diff --git a/clippy_lints/src/implicit_return.rs b/clippy_lints/src/implicit_return.rs index f2f830ca5c09e..fa7b5302cb131 100644 --- a/clippy_lints/src/implicit_return.rs +++ b/clippy_lints/src/implicit_return.rs @@ -13,17 +13,17 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::{Span, SyntaxContext}; declare_clippy_lint! { - /// **What it does:** Checks for missing return statements at the end of a block. + /// ### What it does + /// Checks for missing return statements at the end of a block. /// - /// **Why is this bad?** Actually omitting the return keyword is idiomatic Rust code. Programmers + /// ### Why is this bad? + /// Actually omitting the return keyword is idiomatic Rust code. Programmers /// coming from other languages might prefer the expressiveness of `return`. It's possible to miss /// the last returning statement because the only difference is a missing `;`. Especially in bigger /// code with multiple return paths having a `return` keyword makes it easier to find the /// corresponding statements. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// fn foo(x: usize) -> usize { /// x diff --git a/clippy_lints/src/implicit_saturating_sub.rs b/clippy_lints/src/implicit_saturating_sub.rs index 4069a685ea0a4..0a7d31dce2fd5 100644 --- a/clippy_lints/src/implicit_saturating_sub.rs +++ b/clippy_lints/src/implicit_saturating_sub.rs @@ -8,14 +8,13 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for implicit saturating subtraction. + /// ### What it does + /// Checks for implicit saturating subtraction. /// - /// **Why is this bad?** Simplicity and readability. Instead we can easily use an builtin function. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// Simplicity and readability. Instead we can easily use an builtin function. /// + /// ### Example /// ```rust /// let end: u32 = 10; /// let start: u32 = 5; diff --git a/clippy_lints/src/inconsistent_struct_constructor.rs b/clippy_lints/src/inconsistent_struct_constructor.rs index 3b635071f28aa..1f8240a1f636a 100644 --- a/clippy_lints/src/inconsistent_struct_constructor.rs +++ b/clippy_lints/src/inconsistent_struct_constructor.rs @@ -10,11 +10,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::symbol::Symbol; declare_clippy_lint! { - /// **What it does:** Checks for struct constructors where all fields are shorthand and + /// ### What it does + /// Checks for struct constructors where all fields are shorthand and /// the order of the field init shorthand in the constructor is inconsistent /// with the order in the struct definition. /// - /// **Why is this bad?** Since the order of fields in a constructor doesn't affect the + /// ### Why is this bad? + /// Since the order of fields in a constructor doesn't affect the /// resulted instance as the below example indicates, /// /// ```rust @@ -32,10 +34,7 @@ declare_clippy_lint! { /// /// inconsistent order can be confusing and decreases readability and consistency. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// struct Foo { /// x: i32, diff --git a/clippy_lints/src/indexing_slicing.rs b/clippy_lints/src/indexing_slicing.rs index bfa284f333a1a..8c1f107330955 100644 --- a/clippy_lints/src/indexing_slicing.rs +++ b/clippy_lints/src/indexing_slicing.rs @@ -10,14 +10,17 @@ use rustc_middle::ty; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for out of bounds array indexing with a constant + /// ### What it does + /// Checks for out of bounds array indexing with a constant /// index. /// - /// **Why is this bad?** This will always panic at runtime. + /// ### Why is this bad? + /// This will always panic at runtime. /// - /// **Known problems:** Hopefully none. + /// ### Known problems + /// Hopefully none. /// - /// **Example:** + /// ### Example /// ```no_run /// # #![allow(const_err)] /// let x = [1, 2, 3, 4]; @@ -36,16 +39,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of indexing or slicing. Arrays are special cases, this lint + /// ### What it does + /// Checks for usage of indexing or slicing. Arrays are special cases, this lint /// does report on arrays if we can tell that slicing operations are in bounds and does not /// lint on constant `usize` indexing on arrays because that is handled by rustc's `const_err` lint. /// - /// **Why is this bad?** Indexing and slicing can panic at runtime and there are + /// ### Why is this bad? + /// Indexing and slicing can panic at runtime and there are /// safe alternatives. /// - /// **Known problems:** Hopefully none. + /// ### Known problems + /// Hopefully none. /// - /// **Example:** + /// ### Example /// ```rust,no_run /// // Vector /// let x = vec![0; 5]; diff --git a/clippy_lints/src/infinite_iter.rs b/clippy_lints/src/infinite_iter.rs index 295a4e1fccb0a..2411a3175b919 100644 --- a/clippy_lints/src/infinite_iter.rs +++ b/clippy_lints/src/infinite_iter.rs @@ -7,14 +7,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::symbol::{sym, Symbol}; declare_clippy_lint! { - /// **What it does:** Checks for iteration that is guaranteed to be infinite. + /// ### What it does + /// Checks for iteration that is guaranteed to be infinite. /// - /// **Why is this bad?** While there may be places where this is acceptable + /// ### Why is this bad? + /// While there may be places where this is acceptable /// (e.g., in event streams), in most cases this is simply an error. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```no_run /// use std::iter; /// @@ -26,15 +26,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for iteration that may be infinite. + /// ### What it does + /// Checks for iteration that may be infinite. /// - /// **Why is this bad?** While there may be places where this is acceptable + /// ### Why is this bad? + /// While there may be places where this is acceptable /// (e.g., in event streams), in most cases this is simply an error. /// - /// **Known problems:** The code may have a condition to stop iteration, but + /// ### Known problems + /// The code may have a condition to stop iteration, but /// this lint is not clever enough to analyze it. /// - /// **Example:** + /// ### Example /// ```rust /// let infinite_iter = 0..; /// [0..].iter().zip(infinite_iter.take_while(|x| *x > 5)); diff --git a/clippy_lints/src/inherent_impl.rs b/clippy_lints/src/inherent_impl.rs index 9641784eb9a27..d87055c842c8c 100644 --- a/clippy_lints/src/inherent_impl.rs +++ b/clippy_lints/src/inherent_impl.rs @@ -10,13 +10,13 @@ use rustc_span::Span; use std::collections::hash_map::Entry; declare_clippy_lint! { - /// **What it does:** Checks for multiple inherent implementations of a struct + /// ### What it does + /// Checks for multiple inherent implementations of a struct /// - /// **Why is this bad?** Splitting the implementation of a type makes the code harder to navigate. + /// ### Why is this bad? + /// Splitting the implementation of a type makes the code harder to navigate. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// struct X; /// impl X { diff --git a/clippy_lints/src/inherent_to_string.rs b/clippy_lints/src/inherent_to_string.rs index b023e13e846c7..b62fad4bd3958 100644 --- a/clippy_lints/src/inherent_to_string.rs +++ b/clippy_lints/src/inherent_to_string.rs @@ -8,14 +8,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for the definition of inherent methods with a signature of `to_string(&self) -> String`. + /// ### What it does + /// Checks for the definition of inherent methods with a signature of `to_string(&self) -> String`. /// - /// **Why is this bad?** This method is also implicitly defined if a type implements the `Display` trait. As the functionality of `Display` is much more versatile, it should be preferred. + /// ### Why is this bad? + /// This method is also implicitly defined if a type implements the `Display` trait. As the functionality of `Display` is much more versatile, it should be preferred. /// - /// **Known problems:** None - /// - /// ** Example:** + /// ### Known problems + /// None /// + /// ### Example /// ```rust /// // Bad /// pub struct A; @@ -45,14 +47,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for the definition of inherent methods with a signature of `to_string(&self) -> String` and if the type implementing this method also implements the `Display` trait. - /// - /// **Why is this bad?** This method is also implicitly defined if a type implements the `Display` trait. The less versatile inherent method will then shadow the implementation introduced by `Display`. + /// ### What it does + /// Checks for the definition of inherent methods with a signature of `to_string(&self) -> String` and if the type implementing this method also implements the `Display` trait. /// - /// **Known problems:** None + /// ### Why is this bad? + /// This method is also implicitly defined if a type implements the `Display` trait. The less versatile inherent method will then shadow the implementation introduced by `Display`. /// - /// ** Example:** + /// ### Known problems + /// None /// + /// ### Example /// ```rust /// // Bad /// use std::fmt; diff --git a/clippy_lints/src/inline_fn_without_body.rs b/clippy_lints/src/inline_fn_without_body.rs index 20f00bd51ba86..3e3df903f17cf 100644 --- a/clippy_lints/src/inline_fn_without_body.rs +++ b/clippy_lints/src/inline_fn_without_body.rs @@ -10,14 +10,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::{sym, Symbol}; declare_clippy_lint! { - /// **What it does:** Checks for `#[inline]` on trait methods without bodies + /// ### What it does + /// Checks for `#[inline]` on trait methods without bodies /// - /// **Why is this bad?** Only implementations of trait methods may be inlined. + /// ### Why is this bad? + /// Only implementations of trait methods may be inlined. /// The inline attribute is ignored for trait methods without bodies. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// trait Animal { /// #[inline] diff --git a/clippy_lints/src/int_plus_one.rs b/clippy_lints/src/int_plus_one.rs index c4a1222b51fbe..49b69dd072a21 100644 --- a/clippy_lints/src/int_plus_one.rs +++ b/clippy_lints/src/int_plus_one.rs @@ -8,13 +8,13 @@ use rustc_lint::{EarlyContext, EarlyLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for usage of `x >= y + 1` or `x - 1 >= y` (and `<=`) in a block + /// ### What it does + /// Checks for usage of `x >= y + 1` or `x - 1 >= y` (and `<=`) in a block /// - /// **Why is this bad?** Readability -- better to use `> y` instead of `>= y + 1`. + /// ### Why is this bad? + /// Readability -- better to use `> y` instead of `>= y + 1`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let x = 1; /// # let y = 1; diff --git a/clippy_lints/src/integer_division.rs b/clippy_lints/src/integer_division.rs index e5482f675e78b..a0e6f12b8122e 100644 --- a/clippy_lints/src/integer_division.rs +++ b/clippy_lints/src/integer_division.rs @@ -5,15 +5,15 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for division of integers + /// ### What it does + /// Checks for division of integers /// - /// **Why is this bad?** When outside of some very specific algorithms, + /// ### Why is this bad? + /// When outside of some very specific algorithms, /// integer division is very often a mistake because it discards the /// remainder. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// // Bad /// let x = 3 / 2; diff --git a/clippy_lints/src/invalid_upcast_comparisons.rs b/clippy_lints/src/invalid_upcast_comparisons.rs index 37011f5578dc8..3b28b1212048a 100644 --- a/clippy_lints/src/invalid_upcast_comparisons.rs +++ b/clippy_lints/src/invalid_upcast_comparisons.rs @@ -14,18 +14,20 @@ use clippy_utils::source::snippet; use clippy_utils::{comparisons, sext}; declare_clippy_lint! { - /// **What it does:** Checks for comparisons where the relation is always either + /// ### What it does + /// Checks for comparisons where the relation is always either /// true or false, but where one side has been upcast so that the comparison is /// necessary. Only integer types are checked. /// - /// **Why is this bad?** An expression like `let x : u8 = ...; (x as u32) > 300` + /// ### Why is this bad? + /// An expression like `let x : u8 = ...; (x as u32) > 300` /// will mistakenly imply that it is possible for `x` to be outside the range of /// `u8`. /// - /// **Known problems:** + /// ### Known problems /// https://github.com/rust-lang/rust-clippy/issues/886 /// - /// **Example:** + /// ### Example /// ```rust /// let x: u8 = 1; /// (x as u32) > 300; diff --git a/clippy_lints/src/items_after_statements.rs b/clippy_lints/src/items_after_statements.rs index c69571f32a244..429c6ed7d2d77 100644 --- a/clippy_lints/src/items_after_statements.rs +++ b/clippy_lints/src/items_after_statements.rs @@ -7,15 +7,15 @@ use rustc_middle::lint::in_external_macro; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for items declared after some statement in a block. + /// ### What it does + /// Checks for items declared after some statement in a block. /// - /// **Why is this bad?** Items live for the entire scope they are declared + /// ### Why is this bad? + /// Items live for the entire scope they are declared /// in. But statements are processed in order. This might cause confusion as /// it's hard to figure out which item is meant in a statement. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// // Bad /// fn foo() { diff --git a/clippy_lints/src/large_const_arrays.rs b/clippy_lints/src/large_const_arrays.rs index 48dc5fefe9978..5d4e06c2af082 100644 --- a/clippy_lints/src/large_const_arrays.rs +++ b/clippy_lints/src/large_const_arrays.rs @@ -11,15 +11,15 @@ use rustc_span::{BytePos, Pos, Span}; use rustc_typeck::hir_ty_to_ty; declare_clippy_lint! { - /// **What it does:** Checks for large `const` arrays that should + /// ### What it does + /// Checks for large `const` arrays that should /// be defined as `static` instead. /// - /// **Why is this bad?** Performance: const variables are inlined upon use. + /// ### Why is this bad? + /// Performance: const variables are inlined upon use. /// Static items result in only one instance and has a fixed location in memory. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// // Bad /// pub const a = [0u32; 1_000_000]; diff --git a/clippy_lints/src/large_enum_variant.rs b/clippy_lints/src/large_enum_variant.rs index f166748d86b81..cde2336b690fd 100644 --- a/clippy_lints/src/large_enum_variant.rs +++ b/clippy_lints/src/large_enum_variant.rs @@ -10,20 +10,22 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_target::abi::LayoutOf; declare_clippy_lint! { - /// **What it does:** Checks for large size differences between variants on + /// ### What it does + /// Checks for large size differences between variants on /// `enum`s. /// - /// **Why is this bad?** Enum size is bounded by the largest variant. Having a + /// ### Why is this bad? + /// Enum size is bounded by the largest variant. Having a /// large variant can penalize the memory layout of that enum. /// - /// **Known problems:** This lint obviously cannot take the distribution of + /// ### Known problems + /// This lint obviously cannot take the distribution of /// variants in your running program into account. It is possible that the /// smaller variants make up less than 1% of all instances, in which case /// the overhead is negligible and the boxing is counter-productive. Always /// measure the change this lint suggests. /// - /// **Example:** - /// + /// ### Example /// ```rust /// // Bad /// enum Test { diff --git a/clippy_lints/src/large_stack_arrays.rs b/clippy_lints/src/large_stack_arrays.rs index c46b98022c6ca..7088630bfdbb4 100644 --- a/clippy_lints/src/large_stack_arrays.rs +++ b/clippy_lints/src/large_stack_arrays.rs @@ -10,13 +10,13 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use crate::rustc_target::abi::LayoutOf; declare_clippy_lint! { - /// **What it does:** Checks for local arrays that may be too large. + /// ### What it does + /// Checks for local arrays that may be too large. /// - /// **Why is this bad?** Large local arrays may cause stack overflow. + /// ### Why is this bad? + /// Large local arrays may cause stack overflow. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// let a = [0u32; 1_000_000]; /// ``` diff --git a/clippy_lints/src/len_zero.rs b/clippy_lints/src/len_zero.rs index 892b3af0b3203..b66d7a9f7294f 100644 --- a/clippy_lints/src/len_zero.rs +++ b/clippy_lints/src/len_zero.rs @@ -18,17 +18,17 @@ use rustc_span::{ }; declare_clippy_lint! { - /// **What it does:** Checks for getting the length of something via `.len()` + /// ### What it does + /// Checks for getting the length of something via `.len()` /// just to compare to zero, and suggests using `.is_empty()` where applicable. /// - /// **Why is this bad?** Some structures can answer `.is_empty()` much faster + /// ### Why is this bad? + /// Some structures can answer `.is_empty()` much faster /// than calculating their length. So it is good to get into the habit of using /// `.is_empty()`, and having it is cheap. /// Besides, it makes the intent clearer than a manual comparison in some contexts. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// if x.len() == 0 { /// .. @@ -52,18 +52,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for items that implement `.len()` but not + /// ### What it does + /// Checks for items that implement `.len()` but not /// `.is_empty()`. /// - /// **Why is this bad?** It is good custom to have both methods, because for + /// ### Why is this bad? + /// It is good custom to have both methods, because for /// some data structures, asking about the length will be a costly operation, /// whereas `.is_empty()` can usually answer in constant time. Also it used to /// lead to false positives on the [`len_zero`](#len_zero) lint – currently that /// lint will ignore such entities. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// impl X { /// pub fn len(&self) -> usize { @@ -77,17 +77,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for comparing to an empty slice such as `""` or `[]`, + /// ### What it does + /// Checks for comparing to an empty slice such as `""` or `[]`, /// and suggests using `.is_empty()` where applicable. /// - /// **Why is this bad?** Some structures can answer `.is_empty()` much faster + /// ### Why is this bad? + /// Some structures can answer `.is_empty()` much faster /// than checking for equality. So it is good to get into the habit of using /// `.is_empty()`, and having it is cheap. /// Besides, it makes the intent clearer than a manual comparison in some contexts. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// /// ```ignore /// if s == "" { diff --git a/clippy_lints/src/let_if_seq.rs b/clippy_lints/src/let_if_seq.rs index 67eae4d87bbdb..13f0d43cf8dd1 100644 --- a/clippy_lints/src/let_if_seq.rs +++ b/clippy_lints/src/let_if_seq.rs @@ -9,14 +9,14 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for variable declarations immediately followed by a + /// ### What it does + /// Checks for variable declarations immediately followed by a /// conditional affectation. /// - /// **Why is this bad?** This is not idiomatic Rust. + /// ### Why is this bad? + /// This is not idiomatic Rust. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// let foo; /// diff --git a/clippy_lints/src/let_underscore.rs b/clippy_lints/src/let_underscore.rs index e627b1385bc7d..8992d25932cad 100644 --- a/clippy_lints/src/let_underscore.rs +++ b/clippy_lints/src/let_underscore.rs @@ -9,15 +9,15 @@ use rustc_middle::ty::subst::GenericArgKind; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for `let _ = <expr>` + /// ### What it does + /// Checks for `let _ = <expr>` /// where expr is #[must_use] /// - /// **Why is this bad?** It's better to explicitly + /// ### Why is this bad? + /// It's better to explicitly /// handle the value of a #[must_use] expr /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// fn f() -> Result<u32, u32> { /// Ok(0) @@ -33,17 +33,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `let _ = sync_lock` + /// ### What it does + /// Checks for `let _ = sync_lock` /// - /// **Why is this bad?** This statement immediately drops the lock instead of + /// ### Why is this bad? + /// This statement immediately drops the lock instead of /// extending its lifetime to the end of the scope, which is often not intended. /// To extend lock lifetime to the end of the scope, use an underscore-prefixed /// name instead (i.e. _lock). If you want to explicitly drop the lock, /// `std::mem::drop` conveys your intention better and is less error-prone. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// /// Bad: /// ```rust,ignore @@ -60,19 +60,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `let _ = <expr>` + /// ### What it does + /// Checks for `let _ = <expr>` /// where expr has a type that implements `Drop` /// - /// **Why is this bad?** This statement immediately drops the initializer + /// ### Why is this bad? + /// This statement immediately drops the initializer /// expression instead of extending its lifetime to the end of the scope, which /// is often not intended. To extend the expression's lifetime to the end of the /// scope, use an underscore-prefixed name instead (i.e. _var). If you want to /// explicitly drop the expression, `std::mem::drop` conveys your intention /// better and is less error-prone. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// /// Bad: /// ```rust,ignore diff --git a/clippy_lints/src/lib.rs b/clippy_lints/src/lib.rs index aa763b5c5e666..3cffb507f703a 100644 --- a/clippy_lints/src/lib.rs +++ b/clippy_lints/src/lib.rs @@ -73,14 +73,13 @@ use rustc_session::Session; /// use clippy_lints::declare_clippy_lint; /// /// declare_clippy_lint! { -/// /// **What it does:** Checks for ... (describe what the lint matches). +/// /// ### What it does +/// /// Checks for ... (describe what the lint matches). /// /// -/// /// **Why is this bad?** Supply the reason for linting the code. -/// /// -/// /// **Known problems:** None. (Or describe where it could go wrong.) -/// /// -/// /// **Example:** +/// /// ### Why is this bad? +/// /// Supply the reason for linting the code. /// /// +/// /// ### Example /// /// ```rust /// /// // Bad /// /// Insert a short example of code that triggers the lint diff --git a/clippy_lints/src/lifetimes.rs b/clippy_lints/src/lifetimes.rs index 5ae68ba5b2fe7..e5e6f8d25cc11 100644 --- a/clippy_lints/src/lifetimes.rs +++ b/clippy_lints/src/lifetimes.rs @@ -18,20 +18,22 @@ use rustc_span::source_map::Span; use rustc_span::symbol::{kw, Symbol}; declare_clippy_lint! { - /// **What it does:** Checks for lifetime annotations which can be removed by + /// ### What it does + /// Checks for lifetime annotations which can be removed by /// relying on lifetime elision. /// - /// **Why is this bad?** The additional lifetimes make the code look more + /// ### Why is this bad? + /// The additional lifetimes make the code look more /// complicated, while there is nothing out of the ordinary going on. Removing /// them leads to more readable code. /// - /// **Known problems:** + /// ### Known problems /// - We bail out if the function has a `where` clause where lifetimes /// are mentioned due to potenial false positives. /// - Lifetime bounds such as `impl Foo + 'a` and `T: 'a` must be elided with the /// placeholder notation `'_` because the fully elided notation leaves the type bound to `'static`. /// - /// **Example:** + /// ### Example /// ```rust /// // Bad: unnecessary lifetime annotations /// fn in_and_out<'a>(x: &'a u8, y: u8) -> &'a u8 { @@ -50,16 +52,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for lifetimes in generics that are never used + /// ### What it does + /// Checks for lifetimes in generics that are never used /// anywhere else. /// - /// **Why is this bad?** The additional lifetimes make the code look more + /// ### Why is this bad? + /// The additional lifetimes make the code look more /// complicated, while there is nothing out of the ordinary going on. Removing /// them leads to more readable code. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// // Bad: unnecessary lifetimes /// fn unused_lifetime<'a>(x: u8) { diff --git a/clippy_lints/src/literal_representation.rs b/clippy_lints/src/literal_representation.rs index e0c5578bd603f..699ddce0cff90 100644 --- a/clippy_lints/src/literal_representation.rs +++ b/clippy_lints/src/literal_representation.rs @@ -16,15 +16,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use std::iter; declare_clippy_lint! { - /// **What it does:** Warns if a long integral or floating-point constant does + /// ### What it does + /// Warns if a long integral or floating-point constant does /// not contain underscores. /// - /// **Why is this bad?** Reading long numbers is difficult without separators. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// Reading long numbers is difficult without separators. /// + /// ### Example /// ```rust /// // Bad /// let x: u64 = 61864918973511; @@ -38,17 +37,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Warns for mistyped suffix in literals + /// ### What it does + /// Warns for mistyped suffix in literals /// - /// **Why is this bad?** This is most probably a typo + /// ### Why is this bad? + /// This is most probably a typo /// - /// **Known problems:** + /// ### Known problems /// - Recommends a signed suffix, even though the number might be too big and an unsigned /// suffix is required /// - Does not match on `_127` since that is a valid grouping for decimal and octal numbers /// - /// **Example:** - /// + /// ### Example /// ```rust /// // Probably mistyped /// 2_32; @@ -62,16 +62,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Warns if an integral or floating-point constant is + /// ### What it does + /// Warns if an integral or floating-point constant is /// grouped inconsistently with underscores. /// - /// **Why is this bad?** Readers may incorrectly interpret inconsistently + /// ### Why is this bad? + /// Readers may incorrectly interpret inconsistently /// grouped digits. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// // Bad /// let x: u64 = 618_64_9189_73_511; @@ -85,15 +84,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Warns if hexadecimal or binary literals are not grouped + /// ### What it does + /// Warns if hexadecimal or binary literals are not grouped /// by nibble or byte. /// - /// **Why is this bad?** Negatively impacts readability. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// Negatively impacts readability. /// + /// ### Example /// ```rust /// let x: u32 = 0xFFF_FFF; /// let y: u8 = 0b01_011_101; @@ -104,16 +102,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Warns if the digits of an integral or floating-point + /// ### What it does + /// Warns if the digits of an integral or floating-point /// constant are grouped into groups that /// are too large. /// - /// **Why is this bad?** Negatively impacts readability. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// Negatively impacts readability. /// + /// ### Example /// ```rust /// let x: u64 = 6186491_8973511; /// ``` @@ -123,15 +120,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Warns if there is a better representation for a numeric literal. + /// ### What it does + /// Warns if there is a better representation for a numeric literal. /// - /// **Why is this bad?** Especially for big powers of 2 a hexadecimal representation is more + /// ### Why is this bad? + /// Especially for big powers of 2 a hexadecimal representation is more /// readable than a decimal representation. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// `255` => `0xFF` /// `65_535` => `0xFFFF` /// `4_042_322_160` => `0xF0F0_F0F0` diff --git a/clippy_lints/src/loops/mod.rs b/clippy_lints/src/loops/mod.rs index 56a123b69c6ae..7ca54d5397205 100644 --- a/clippy_lints/src/loops/mod.rs +++ b/clippy_lints/src/loops/mod.rs @@ -26,14 +26,14 @@ use rustc_span::source_map::Span; use utils::{get_span_of_entire_for_loop, make_iterator_snippet, IncrementVisitor, InitializeVisitor}; declare_clippy_lint! { - /// **What it does:** Checks for for-loops that manually copy items between + /// ### What it does + /// Checks for for-loops that manually copy items between /// slices that could be optimized by having a memcpy. /// - /// **Why is this bad?** It is not as fast as a memcpy. + /// ### Why is this bad? + /// It is not as fast as a memcpy. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let src = vec![1]; /// # let mut dst = vec![0; 65]; @@ -53,15 +53,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for looping over the range of `0..len` of some + /// ### What it does + /// Checks for looping over the range of `0..len` of some /// collection just to get the values by index. /// - /// **Why is this bad?** Just iterating the collection itself makes the intent + /// ### Why is this bad? + /// Just iterating the collection itself makes the intent /// more clear and is probably faster. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let vec = vec!['a', 'b', 'c']; /// for i in 0..vec.len() { @@ -81,15 +81,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for loops on `x.iter()` where `&x` will do, and + /// ### What it does + /// Checks for loops on `x.iter()` where `&x` will do, and /// suggests the latter. /// - /// **Why is this bad?** Readability. + /// ### Why is this bad? + /// Readability. /// - /// **Known problems:** False negatives. We currently only warn on some known + /// ### Known problems + /// False negatives. We currently only warn on some known /// types. /// - /// **Example:** + /// ### Example /// ```rust /// // with `y` a `Vec` or slice: /// # let y = vec![1]; @@ -110,14 +113,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for loops on `y.into_iter()` where `y` will do, and + /// ### What it does + /// Checks for loops on `y.into_iter()` where `y` will do, and /// suggests the latter. /// - /// **Why is this bad?** Readability. + /// ### Why is this bad? + /// Readability. /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```rust /// # let y = vec![1]; /// // with `y` a `Vec` or slice: @@ -138,18 +141,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for loops on `x.next()`. + /// ### What it does + /// Checks for loops on `x.next()`. /// - /// **Why is this bad?** `next()` returns either `Some(value)` if there was a + /// ### Why is this bad? + /// `next()` returns either `Some(value)` if there was a /// value, or `None` otherwise. The insidious thing is that `Option<_>` /// implements `IntoIterator`, so that possibly one value will be iterated, /// leading to some hard to find bugs. No one will want to write such code /// [except to win an Underhanded Rust /// Contest](https://www.reddit.com/r/rust/comments/3hb0wm/underhanded_rust_contest/cu5yuhr). /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// for x in y.next() { /// .. @@ -161,14 +164,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `for` loops over `Option` or `Result` values. + /// ### What it does + /// Checks for `for` loops over `Option` or `Result` values. /// - /// **Why is this bad?** Readability. This is more clearly expressed as an `if + /// ### Why is this bad? + /// Readability. This is more clearly expressed as an `if /// let`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let opt = Some(1); /// @@ -204,15 +207,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Detects `loop + match` combinations that are easier + /// ### What it does + /// Detects `loop + match` combinations that are easier /// written as a `while let` loop. /// - /// **Why is this bad?** The `while let` loop is usually shorter and more + /// ### Why is this bad? + /// The `while let` loop is usually shorter and more /// readable. /// - /// **Known problems:** Sometimes the wrong binding is displayed ([#383](https://github.com/rust-lang/rust-clippy/issues/383)). + /// ### Known problems + /// Sometimes the wrong binding is displayed ([#383](https://github.com/rust-lang/rust-clippy/issues/383)). /// - /// **Example:** + /// ### Example /// ```rust,no_run /// # let y = Some(1); /// loop { @@ -233,16 +239,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for functions collecting an iterator when collect + /// ### What it does + /// Checks for functions collecting an iterator when collect /// is not needed. /// - /// **Why is this bad?** `collect` causes the allocation of a new data structure, + /// ### Why is this bad? + /// `collect` causes the allocation of a new data structure, /// when this allocation may not be needed. /// - /// **Known problems:** - /// None - /// - /// **Example:** + /// ### Example /// ```rust /// # let iterator = vec![1].into_iter(); /// let len = iterator.clone().collect::<Vec<_>>().len(); @@ -255,15 +260,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks `for` loops over slices with an explicit counter + /// ### What it does + /// Checks `for` loops over slices with an explicit counter /// and suggests the use of `.enumerate()`. /// - /// **Why is it bad?** Using `.enumerate()` makes the intent more clear, + /// ### Why is this bad? + /// Using `.enumerate()` makes the intent more clear, /// declutters the code and may be faster in some instances. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let v = vec![1]; /// # fn bar(bar: usize, baz: usize) {} @@ -285,9 +290,11 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for empty `loop` expressions. + /// ### What it does + /// Checks for empty `loop` expressions. /// - /// **Why is this bad?** These busy loops burn CPU cycles without doing + /// ### Why is this bad? + /// These busy loops burn CPU cycles without doing /// anything. It is _almost always_ a better idea to `panic!` than to have /// a busy loop. /// @@ -306,9 +313,7 @@ declare_clippy_lint! { /// - [`x86_64::instructions::hlt`](https://docs.rs/x86_64/0.12.2/x86_64/instructions/fn.hlt.html) /// - [`cortex_m::asm::wfi`](https://docs.rs/cortex-m/0.6.3/cortex_m/asm/fn.wfi.html) /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```no_run /// loop {} /// ``` @@ -318,14 +323,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `while let` expressions on iterators. + /// ### What it does + /// Checks for `while let` expressions on iterators. /// - /// **Why is this bad?** Readability. A simple `for` loop is shorter and conveys + /// ### Why is this bad? + /// Readability. A simple `for` loop is shorter and conveys /// the intent better. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// while let Some(val) = iter() { /// .. @@ -337,15 +342,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for iterating a map (`HashMap` or `BTreeMap`) and + /// ### What it does + /// Checks for iterating a map (`HashMap` or `BTreeMap`) and /// ignoring either the keys or values. /// - /// **Why is this bad?** Readability. There are `keys` and `values` methods that + /// ### Why is this bad? + /// Readability. There are `keys` and `values` methods that /// can be used to express that don't need the values or keys. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// for (k, _) in &map { /// .. @@ -365,15 +370,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for loops that will always `break`, `return` or + /// ### What it does + /// Checks for loops that will always `break`, `return` or /// `continue` an outer loop. /// - /// **Why is this bad?** This loop never loops, all it does is obfuscating the + /// ### Why is this bad? + /// This loop never loops, all it does is obfuscating the /// code. /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```rust /// loop { /// ..; @@ -386,13 +391,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for loops which have a range bound that is a mutable variable - /// - /// **Why is this bad?** One might think that modifying the mutable variable changes the loop bounds + /// ### What it does + /// Checks for loops which have a range bound that is a mutable variable /// - /// **Known problems:** None + /// ### Why is this bad? + /// One might think that modifying the mutable variable changes the loop bounds /// - /// **Example:** + /// ### Example /// ```rust /// let mut foo = 42; /// for i in 0..foo { @@ -406,17 +411,20 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks whether variables used within while loop condition + /// ### What it does + /// Checks whether variables used within while loop condition /// can be (and are) mutated in the body. /// - /// **Why is this bad?** If the condition is unchanged, entering the body of the loop + /// ### Why is this bad? + /// If the condition is unchanged, entering the body of the loop /// will lead to an infinite loop. /// - /// **Known problems:** If the `while`-loop is in a closure, the check for mutation of the + /// ### Known problems + /// If the `while`-loop is in a closure, the check for mutation of the /// condition variables in the body can cause false negatives. For example when only `Upvar` `a` is /// in the condition and only `Upvar` `b` gets mutated in the body, the lint will not trigger. /// - /// **Example:** + /// ### Example /// ```rust /// let i = 0; /// while i > 10 { @@ -429,15 +437,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks whether a for loop is being used to push a constant + /// ### What it does + /// Checks whether a for loop is being used to push a constant /// value into a Vec. /// - /// **Why is this bad?** This kind of operation can be expressed more succinctly with + /// ### Why is this bad? + /// This kind of operation can be expressed more succinctly with /// `vec![item;SIZE]` or `vec.resize(NEW_SIZE, item)` and using these alternatives may also /// have better performance. - /// **Known problems:** None /// - /// **Example:** + /// ### Example /// ```rust /// let item1 = 2; /// let item2 = 3; @@ -462,13 +471,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks whether a for loop has a single element. + /// ### What it does + /// Checks whether a for loop has a single element. /// - /// **Why is this bad?** There is no reason to have a loop of a + /// ### Why is this bad? + /// There is no reason to have a loop of a /// single element. - /// **Known problems:** None /// - /// **Example:** + /// ### Example /// ```rust /// let item1 = 2; /// for item in &[item1] { @@ -487,15 +497,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Check for unnecessary `if let` usage in a for loop + /// ### What it does + /// Check for unnecessary `if let` usage in a for loop /// where only the `Some` or `Ok` variant of the iterator element is used. /// - /// **Why is this bad?** It is verbose and can be simplified + /// ### Why is this bad? + /// It is verbose and can be simplified /// by first calling the `flatten` method on the `Iterator`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// /// ```rust /// let x = vec![Some(1), Some(2), Some(3)]; diff --git a/clippy_lints/src/macro_use.rs b/clippy_lints/src/macro_use.rs index 66479ae264e4f..a371f8bbd3cb4 100644 --- a/clippy_lints/src/macro_use.rs +++ b/clippy_lints/src/macro_use.rs @@ -12,14 +12,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::{edition::Edition, sym, Span}; declare_clippy_lint! { - /// **What it does:** Checks for `#[macro_use] use...`. + /// ### What it does + /// Checks for `#[macro_use] use...`. /// - /// **Why is this bad?** Since the Rust 2018 edition you can import + /// ### Why is this bad? + /// Since the Rust 2018 edition you can import /// macro's directly, this is considered idiomatic. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// #[macro_use] /// use some_macro; diff --git a/clippy_lints/src/main_recursion.rs b/clippy_lints/src/main_recursion.rs index 07d8a440aea4c..776e4b3fe768a 100644 --- a/clippy_lints/src/main_recursion.rs +++ b/clippy_lints/src/main_recursion.rs @@ -7,14 +7,14 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_tool_lint, impl_lint_pass}; declare_clippy_lint! { - /// **What it does:** Checks for recursion using the entrypoint. + /// ### What it does + /// Checks for recursion using the entrypoint. /// - /// **Why is this bad?** Apart from special setups (which we could detect following attributes like #![no_std]), + /// ### Why is this bad? + /// Apart from special setups (which we could detect following attributes like #![no_std]), /// recursing into main() seems like an unintuitive antipattern we should be able to detect. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```no_run /// fn main() { /// main(); diff --git a/clippy_lints/src/manual_async_fn.rs b/clippy_lints/src/manual_async_fn.rs index 5d88ff3b99f31..8e1385fb83a25 100644 --- a/clippy_lints/src/manual_async_fn.rs +++ b/clippy_lints/src/manual_async_fn.rs @@ -14,14 +14,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::{sym, Span}; declare_clippy_lint! { - /// **What it does:** It checks for manual implementations of `async` functions. + /// ### What it does + /// It checks for manual implementations of `async` functions. /// - /// **Why is this bad?** It's more idiomatic to use the dedicated syntax. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// It's more idiomatic to use the dedicated syntax. /// + /// ### Example /// ```rust /// use std::future::Future; /// diff --git a/clippy_lints/src/manual_map.rs b/clippy_lints/src/manual_map.rs index 563d5cdb5fb56..7dec1595e0d10 100644 --- a/clippy_lints/src/manual_map.rs +++ b/clippy_lints/src/manual_map.rs @@ -16,14 +16,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::{sym, SyntaxContext}; declare_clippy_lint! { - /// **What it does:** Checks for usages of `match` which could be implemented using `map` + /// ### What it does + /// Checks for usages of `match` which could be implemented using `map` /// - /// **Why is this bad?** Using the `map` method is clearer and more concise. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// Using the `map` method is clearer and more concise. /// + /// ### Example /// ```rust /// match Some(0) { /// Some(x) => Some(x + 1), diff --git a/clippy_lints/src/manual_non_exhaustive.rs b/clippy_lints/src/manual_non_exhaustive.rs index 54f714b54b657..335ea001ee476 100644 --- a/clippy_lints/src/manual_non_exhaustive.rs +++ b/clippy_lints/src/manual_non_exhaustive.rs @@ -11,15 +11,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::{sym, Span}; declare_clippy_lint! { - /// **What it does:** Checks for manual implementations of the non-exhaustive pattern. + /// ### What it does + /// Checks for manual implementations of the non-exhaustive pattern. /// - /// **Why is this bad?** Using the #[non_exhaustive] attribute expresses better the intent + /// ### Why is this bad? + /// Using the #[non_exhaustive] attribute expresses better the intent /// and allows possible optimizations when applied to enums. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// struct S { /// pub a: i32, diff --git a/clippy_lints/src/manual_ok_or.rs b/clippy_lints/src/manual_ok_or.rs index 847c8c648b00a..b2f287af6971a 100644 --- a/clippy_lints/src/manual_ok_or.rs +++ b/clippy_lints/src/manual_ok_or.rs @@ -13,15 +13,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::symbol::sym; declare_clippy_lint! { - /// **What it does:** + /// ### What it does + /// /// Finds patterns that reimplement `Option::ok_or`. /// - /// **Why is this bad?** - /// Concise code helps focusing on behavior instead of boilerplate. + /// ### Why is this bad? /// - /// **Known problems:** None. + /// Concise code helps focusing on behavior instead of boilerplate. /// - /// **Examples:** + /// ### Examples /// ```rust /// let foo: Option<i32> = None; /// foo.map_or(Err("error"), |v| Ok(v)); diff --git a/clippy_lints/src/manual_strip.rs b/clippy_lints/src/manual_strip.rs index 61b5fe81fa9e6..db12c377488b0 100644 --- a/clippy_lints/src/manual_strip.rs +++ b/clippy_lints/src/manual_strip.rs @@ -18,21 +18,17 @@ use rustc_span::source_map::Spanned; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// Suggests using `strip_{prefix,suffix}` over `str::{starts,ends}_with` and slicing using /// the pattern's length. /// - /// **Why is this bad?** + /// ### Why is this bad? /// Using `str:strip_{prefix,suffix}` is safer and may have better performance as there is no /// slicing which may panic and the compiler does not need to insert this panic code. It is /// also sometimes more readable as it removes the need for duplicating or storing the pattern /// used by `str::{starts,ends}_with` and in the slicing. /// - /// **Known problems:** - /// None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// let s = "hello, world!"; /// if s.starts_with("hello, ") { diff --git a/clippy_lints/src/manual_unwrap_or.rs b/clippy_lints/src/manual_unwrap_or.rs index 9d8d77cf8f089..426789742d51c 100644 --- a/clippy_lints/src/manual_unwrap_or.rs +++ b/clippy_lints/src/manual_unwrap_or.rs @@ -15,15 +15,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// Finds patterns that reimplement `Option::unwrap_or` or `Result::unwrap_or`. /// - /// **Why is this bad?** + /// ### Why is this bad? /// Concise code helps focusing on behavior instead of boilerplate. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let foo: Option<i32> = None; /// match foo { diff --git a/clippy_lints/src/map_clone.rs b/clippy_lints/src/map_clone.rs index e1f80ab025c0a..394606200bb04 100644 --- a/clippy_lints/src/map_clone.rs +++ b/clippy_lints/src/map_clone.rs @@ -15,16 +15,15 @@ use rustc_span::symbol::Ident; use rustc_span::{sym, Span}; declare_clippy_lint! { - /// **What it does:** Checks for usage of `map(|x| x.clone())` or + /// ### What it does + /// Checks for usage of `map(|x| x.clone())` or /// dereferencing closures for `Copy` types, on `Iterator` or `Option`, /// and suggests `cloned()` or `copied()` instead /// - /// **Why is this bad?** Readability, this can be written more concisely - /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Why is this bad? + /// Readability, this can be written more concisely /// + /// ### Example /// ```rust /// let x = vec![42, 43]; /// let y = x.iter(); diff --git a/clippy_lints/src/map_err_ignore.rs b/clippy_lints/src/map_err_ignore.rs index 425a9734e5fee..82d3732326ebb 100644 --- a/clippy_lints/src/map_err_ignore.rs +++ b/clippy_lints/src/map_err_ignore.rs @@ -4,13 +4,13 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for instances of `map_err(|_| Some::Enum)` + /// ### What it does + /// Checks for instances of `map_err(|_| Some::Enum)` /// - /// **Why is this bad?** This `map_err` throws away the original error rather than allowing the enum to contain and report the cause of the error + /// ### Why is this bad? + /// This `map_err` throws away the original error rather than allowing the enum to contain and report the cause of the error /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// Before: /// ```rust /// use std::fmt; diff --git a/clippy_lints/src/map_unit_fn.rs b/clippy_lints/src/map_unit_fn.rs index 57cd907e77e8d..fd40590d077ff 100644 --- a/clippy_lints/src/map_unit_fn.rs +++ b/clippy_lints/src/map_unit_fn.rs @@ -12,16 +12,15 @@ use rustc_span::source_map::Span; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for usage of `option.map(f)` where f is a function + /// ### What it does + /// Checks for usage of `option.map(f)` where f is a function /// or closure that returns the unit type `()`. /// - /// **Why is this bad?** Readability, this can be written more clearly with + /// ### Why is this bad? + /// Readability, this can be written more clearly with /// an if let statement /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// # fn do_stuff() -> Option<String> { Some(String::new()) } /// # fn log_err_msg(foo: String) -> Option<String> { Some(foo) } @@ -54,16 +53,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `result.map(f)` where f is a function + /// ### What it does + /// Checks for usage of `result.map(f)` where f is a function /// or closure that returns the unit type `()`. /// - /// **Why is this bad?** Readability, this can be written more clearly with + /// ### Why is this bad? + /// Readability, this can be written more clearly with /// an if let statement /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// # fn do_stuff() -> Result<String, String> { Ok(String::new()) } /// # fn log_err_msg(foo: String) -> Result<String, String> { Ok(foo) } diff --git a/clippy_lints/src/match_on_vec_items.rs b/clippy_lints/src/match_on_vec_items.rs index ca6fb0831fe22..e66a35452f0d8 100644 --- a/clippy_lints/src/match_on_vec_items.rs +++ b/clippy_lints/src/match_on_vec_items.rs @@ -10,13 +10,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for `match vec[idx]` or `match vec[n..m]`. + /// ### What it does + /// Checks for `match vec[idx]` or `match vec[n..m]`. /// - /// **Why is this bad?** This can panic at runtime. + /// ### Why is this bad? + /// This can panic at runtime. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust, no_run /// let arr = vec![0, 1, 2, 3]; /// let idx = 1; diff --git a/clippy_lints/src/matches.rs b/clippy_lints/src/matches.rs index d7f600b3ab2b0..5360c02f90539 100644 --- a/clippy_lints/src/matches.rs +++ b/clippy_lints/src/matches.rs @@ -35,14 +35,14 @@ use std::iter; use std::ops::Bound; declare_clippy_lint! { - /// **What it does:** Checks for matches with a single arm where an `if let` + /// ### What it does + /// Checks for matches with a single arm where an `if let` /// will usually suffice. /// - /// **Why is this bad?** Just readability – `if let` nests less than a `match`. + /// ### Why is this bad? + /// Just readability – `if let` nests less than a `match`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # fn bar(stool: &str) {} /// # let x = Some("abc"); @@ -63,15 +63,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for matches with two arms where an `if let else` will + /// ### What it does + /// Checks for matches with two arms where an `if let else` will /// usually suffice. /// - /// **Why is this bad?** Just readability – `if let` nests less than a `match`. - /// - /// **Known problems:** Personal style preferences may differ. + /// ### Why is this bad? + /// Just readability – `if let` nests less than a `match`. /// - /// **Example:** + /// ### Known problems + /// Personal style preferences may differ. /// + /// ### Example /// Using `match`: /// /// ```rust @@ -102,16 +104,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for matches where all arms match a reference, + /// ### What it does + /// Checks for matches where all arms match a reference, /// suggesting to remove the reference and deref the matched expression /// instead. It also checks for `if let &foo = bar` blocks. /// - /// **Why is this bad?** It just makes the code less readable. That reference + /// ### Why is this bad? + /// It just makes the code less readable. That reference /// destructuring adds nothing to the code. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// // Bad /// match x { @@ -133,14 +135,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for matches where match expression is a `bool`. It + /// ### What it does + /// Checks for matches where match expression is a `bool`. It /// suggests to replace the expression with an `if...else` block. /// - /// **Why is this bad?** It makes the code less readable. + /// ### Why is this bad? + /// It makes the code less readable. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # fn foo() {} /// # fn bar() {} @@ -167,14 +169,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for overlapping match arms. + /// ### What it does + /// Checks for overlapping match arms. /// - /// **Why is this bad?** It is likely to be an error and if not, makes the code + /// ### Why is this bad? + /// It is likely to be an error and if not, makes the code /// less obvious. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x = 5; /// match x { @@ -189,15 +191,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for arm which matches all errors with `Err(_)` + /// ### What it does + /// Checks for arm which matches all errors with `Err(_)` /// and take drastic actions like `panic!`. /// - /// **Why is this bad?** It is generally a bad practice, similar to + /// ### Why is this bad? + /// It is generally a bad practice, similar to /// catching all exceptions in java with `catch(Exception)` /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x: Result<i32, &str> = Ok(3); /// match x { @@ -211,14 +213,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for match which is used to add a reference to an + /// ### What it does + /// Checks for match which is used to add a reference to an /// `Option` value. /// - /// **Why is this bad?** Using `as_ref()` or `as_mut()` instead is shorter. + /// ### Why is this bad? + /// Using `as_ref()` or `as_mut()` instead is shorter. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x: Option<()> = None; /// @@ -237,14 +239,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for wildcard enum matches using `_`. + /// ### What it does + /// Checks for wildcard enum matches using `_`. /// - /// **Why is this bad?** New enum variants added by library updates can be missed. + /// ### Why is this bad? + /// New enum variants added by library updates can be missed. /// - /// **Known problems:** Suggested replacements may be incorrect if guards exhaustively cover some + /// ### Known problems + /// Suggested replacements may be incorrect if guards exhaustively cover some /// variants, and also may not use correct path to enum if it's not present in the current scope. /// - /// **Example:** + /// ### Example /// ```rust /// # enum Foo { A(usize), B(usize) } /// # let x = Foo::B(1); @@ -266,15 +271,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for wildcard enum matches for a single variant. + /// ### What it does + /// Checks for wildcard enum matches for a single variant. /// - /// **Why is this bad?** New enum variants added by library updates can be missed. + /// ### Why is this bad? + /// New enum variants added by library updates can be missed. /// - /// **Known problems:** Suggested replacements may not use correct path to enum + /// ### Known problems + /// Suggested replacements may not use correct path to enum /// if it's not present in the current scope. /// - /// **Example:** - /// + /// ### Example /// ```rust /// # enum Foo { A, B, C } /// # let x = Foo::B; @@ -298,14 +305,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for wildcard pattern used with others patterns in same match arm. + /// ### What it does + /// Checks for wildcard pattern used with others patterns in same match arm. /// - /// **Why is this bad?** Wildcard pattern already covers any other pattern as it will match anyway. + /// ### Why is this bad? + /// Wildcard pattern already covers any other pattern as it will match anyway. /// It makes the code less readable, especially to spot wildcard pattern use in match arm. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// // Bad /// match "foo" { @@ -325,14 +332,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for matches being used to destructure a single-variant enum + /// ### What it does + /// Checks for matches being used to destructure a single-variant enum /// or tuple struct where a `let` will suffice. /// - /// **Why is this bad?** Just readability – `let` doesn't nest, whereas a `match` does. + /// ### Why is this bad? + /// Just readability – `let` doesn't nest, whereas a `match` does. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// enum Wrapper { /// Data(i32), @@ -360,14 +367,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for useless match that binds to only one value. + /// ### What it does + /// Checks for useless match that binds to only one value. /// - /// **Why is this bad?** Readability and needless complexity. + /// ### Why is this bad? + /// Readability and needless complexity. /// - /// **Known problems:** Suggested replacements may be incorrect when `match` + /// ### Known problems + /// Suggested replacements may be incorrect when `match` /// is actually binding temporary value, bringing a 'dropped while borrowed' error. /// - /// **Example:** + /// ### Example /// ```rust /// # let a = 1; /// # let b = 2; @@ -388,14 +398,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for unnecessary '..' pattern binding on struct when all fields are explicitly matched. + /// ### What it does + /// Checks for unnecessary '..' pattern binding on struct when all fields are explicitly matched. /// - /// **Why is this bad?** Correctness and readability. It's like having a wildcard pattern after + /// ### Why is this bad? + /// Correctness and readability. It's like having a wildcard pattern after /// matching all enum variants explicitly. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # struct A { a: i32 } /// let a = A { a: 5 }; @@ -418,21 +428,23 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Lint for redundant pattern matching over `Result`, `Option`, + /// ### What it does + /// Lint for redundant pattern matching over `Result`, `Option`, /// `std::task::Poll` or `std::net::IpAddr` /// - /// **Why is this bad?** It's more concise and clear to just use the proper + /// ### Why is this bad? + /// It's more concise and clear to just use the proper /// utility function /// - /// **Known problems:** This will change the drop order for the matched type. Both `if let` and + /// ### Known problems + /// This will change the drop order for the matched type. Both `if let` and /// `while let` will drop the value at the end of the block, both `if` and `while` will drop the /// value before entering the block. For most types this change will not matter, but for a few /// types this will not be an acceptable change (e.g. locks). See the /// [reference](https://doc.rust-lang.org/reference/destructors.html#drop-scopes) for more about /// drop order. /// - /// **Example:** - /// + /// ### Example /// ```rust /// # use std::task::Poll; /// # use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; @@ -471,15 +483,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `match` or `if let` expressions producing a + /// ### What it does + /// Checks for `match` or `if let` expressions producing a /// `bool` that could be written using `matches!` /// - /// **Why is this bad?** Readability and needless complexity. + /// ### Why is this bad? + /// Readability and needless complexity. /// - /// **Known problems:** This lint falsely triggers, if there are arms with + /// ### Known problems + /// This lint falsely triggers, if there are arms with /// `cfg` attributes that remove an arm evaluating to `false`. /// - /// **Example:** + /// ### Example /// ```rust /// let x = Some(5); /// @@ -504,17 +519,20 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `match` with identical arm bodies. + /// ### What it does + /// Checks for `match` with identical arm bodies. /// - /// **Why is this bad?** This is probably a copy & paste error. If arm bodies + /// ### Why is this bad? + /// This is probably a copy & paste error. If arm bodies /// are the same on purpose, you can factor them /// [using `|`](https://doc.rust-lang.org/book/patterns.html#multiple-patterns). /// - /// **Known problems:** False positive possible with order dependent `match` + /// ### Known problems + /// False positive possible with order dependent `match` /// (see issue /// [#860](https://github.com/rust-lang/rust-clippy/issues/860)). /// - /// **Example:** + /// ### Example /// ```rust,ignore /// match foo { /// Bar => bar(), diff --git a/clippy_lints/src/mem_discriminant.rs b/clippy_lints/src/mem_discriminant.rs index aca96e06ef2e7..59176c4b84663 100644 --- a/clippy_lints/src/mem_discriminant.rs +++ b/clippy_lints/src/mem_discriminant.rs @@ -9,14 +9,14 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for calls of `mem::discriminant()` on a non-enum type. + /// ### What it does + /// Checks for calls of `mem::discriminant()` on a non-enum type. /// - /// **Why is this bad?** The value of `mem::discriminant()` on non-enum types + /// ### Why is this bad? + /// The value of `mem::discriminant()` on non-enum types /// is unspecified. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// use std::mem; /// diff --git a/clippy_lints/src/mem_forget.rs b/clippy_lints/src/mem_forget.rs index a28cb5f32fe8a..07202a59c4b96 100644 --- a/clippy_lints/src/mem_forget.rs +++ b/clippy_lints/src/mem_forget.rs @@ -5,15 +5,15 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for usage of `std::mem::forget(t)` where `t` is + /// ### What it does + /// Checks for usage of `std::mem::forget(t)` where `t` is /// `Drop`. /// - /// **Why is this bad?** `std::mem::forget(t)` prevents `t` from running its + /// ### Why is this bad? + /// `std::mem::forget(t)` prevents `t` from running its /// destructor, possibly causing leaks. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # use std::mem; /// # use std::rc::Rc; diff --git a/clippy_lints/src/mem_replace.rs b/clippy_lints/src/mem_replace.rs index 183daee361774..3d071c9081be1 100644 --- a/clippy_lints/src/mem_replace.rs +++ b/clippy_lints/src/mem_replace.rs @@ -14,16 +14,16 @@ use rustc_span::source_map::Span; use rustc_span::symbol::sym; declare_clippy_lint! { - /// **What it does:** Checks for `mem::replace()` on an `Option` with + /// ### What it does + /// Checks for `mem::replace()` on an `Option` with /// `None`. /// - /// **Why is this bad?** `Option` already has the method `take()` for + /// ### Why is this bad? + /// `Option` already has the method `take()` for /// taking its current value (Some(..) or None) and replacing it with /// `None`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// use std::mem; /// @@ -41,17 +41,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `mem::replace(&mut _, mem::uninitialized())` + /// ### What it does + /// Checks for `mem::replace(&mut _, mem::uninitialized())` /// and `mem::replace(&mut _, mem::zeroed())`. /// - /// **Why is this bad?** This will lead to undefined behavior even if the + /// ### Why is this bad? + /// This will lead to undefined behavior even if the /// value is overwritten later, because the uninitialized value may be /// observed in the case of a panic. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ``` /// use std::mem; ///# fn may_panic(v: Vec<i32>) -> Vec<i32> { v } @@ -73,15 +72,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `std::mem::replace` on a value of type + /// ### What it does + /// Checks for `std::mem::replace` on a value of type /// `T` with `T::default()`. /// - /// **Why is this bad?** `std::mem` module already has the method `take` to + /// ### Why is this bad? + /// `std::mem` module already has the method `take` to /// take the current value and replace it with the default value of that type. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let mut text = String::from("foo"); /// let replaced = std::mem::replace(&mut text, String::default()); diff --git a/clippy_lints/src/methods/mod.rs b/clippy_lints/src/methods/mod.rs index 283fcf281df18..d3e120238141e 100644 --- a/clippy_lints/src/methods/mod.rs +++ b/clippy_lints/src/methods/mod.rs @@ -80,16 +80,15 @@ use rustc_span::{sym, Span}; use rustc_typeck::hir_ty_to_ty; declare_clippy_lint! { - /// **What it does:** Checks for usages of `cloned()` on an `Iterator` or `Option` where + /// ### What it does + /// Checks for usages of `cloned()` on an `Iterator` or `Option` where /// `copied()` could be used instead. /// - /// **Why is this bad?** `copied()` is better because it guarantees that the type being cloned + /// ### Why is this bad? + /// `copied()` is better because it guarantees that the type being cloned /// implements `Copy`. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// [1, 2, 3].iter().cloned(); /// ``` @@ -103,16 +102,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usages of `Iterator::flat_map()` where `filter_map()` could be + /// ### What it does + /// Checks for usages of `Iterator::flat_map()` where `filter_map()` could be /// used instead. /// - /// **Why is this bad?** When applicable, `filter_map()` is more clear since it shows that + /// ### Why is this bad? + /// When applicable, `filter_map()` is more clear since it shows that /// `Option` is used to produce 0 or 1 items. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// let nums: Vec<i32> = ["1", "2", "whee!"].iter().flat_map(|x| x.parse().ok()).collect(); /// ``` @@ -126,9 +124,11 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `.unwrap()` calls on `Option`s and on `Result`s. + /// ### What it does + /// Checks for `.unwrap()` calls on `Option`s and on `Result`s. /// - /// **Why is this bad?** It is better to handle the `None` or `Err` case, + /// ### Why is this bad? + /// It is better to handle the `None` or `Err` case, /// or at least call `.expect(_)` with a more helpful message. Still, for a lot of /// quick-and-dirty code, `unwrap` is a good choice, which is why this lint is /// `Allow` by default. @@ -141,9 +141,7 @@ declare_clippy_lint! { /// messages on display. Therefore, it may be beneficial to look at the places /// where they may get displayed. Activate this lint to do just that. /// - /// **Known problems:** None. - /// - /// **Examples:** + /// ### Examples /// ```rust /// # let opt = Some(1); /// @@ -171,9 +169,11 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `.expect()` calls on `Option`s and `Result`s. + /// ### What it does + /// Checks for `.expect()` calls on `Option`s and `Result`s. /// - /// **Why is this bad?** Usually it is better to handle the `None` or `Err` case. + /// ### Why is this bad? + /// Usually it is better to handle the `None` or `Err` case. /// Still, for a lot of quick-and-dirty code, `expect` is a good choice, which is why /// this lint is `Allow` by default. /// @@ -181,9 +181,7 @@ declare_clippy_lint! { /// values. Normally, you want to implement more sophisticated error handling, /// and propagate errors upwards with `?` operator. /// - /// **Known problems:** None. - /// - /// **Examples:** + /// ### Examples /// ```rust,ignore /// # let opt = Some(1); /// @@ -213,20 +211,20 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for methods that should live in a trait + /// ### What it does + /// Checks for methods that should live in a trait /// implementation of a `std` trait (see [llogiq's blog /// post](http://llogiq.github.io/2015/07/30/traits.html) for further /// information) instead of an inherent implementation. /// - /// **Why is this bad?** Implementing the traits improve ergonomics for users of + /// ### Why is this bad? + /// Implementing the traits improve ergonomics for users of /// the code, often with very little cost. Also people seeing a `mul(...)` /// method /// may expect `*` to work equally, so you should have good reason to disappoint /// them. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// struct X; /// impl X { @@ -242,7 +240,8 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for methods with certain name prefixes and which + /// ### What it does + /// Checks for methods with certain name prefixes and which /// doesn't match how self is taken. The actual rules are: /// /// |Prefix |Postfix |`self` taken | `self` type | @@ -265,13 +264,12 @@ declare_clippy_lint! { /// Please find more info here: /// https://rust-lang.github.io/api-guidelines/naming.html#ad-hoc-conversions-follow-as_-to_-into_-conventions-c-conv /// - /// **Why is this bad?** Consistency breeds readability. If you follow the + /// ### Why is this bad? + /// Consistency breeds readability. If you follow the /// conventions, your users won't be surprised that they, e.g., need to supply a /// mutable reference to a `as_..` function. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # struct X; /// impl X { @@ -287,14 +285,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `ok().expect(..)`. + /// ### What it does + /// Checks for usage of `ok().expect(..)`. /// - /// **Why is this bad?** Because you usually call `expect()` on the `Result` + /// ### Why is this bad? + /// Because you usually call `expect()` on the `Result` /// directly to get a better error message. /// - /// **Known problems:** The error type needs to implement `Debug` + /// ### Known problems + /// The error type needs to implement `Debug` /// - /// **Example:** + /// ### Example /// ```rust /// # let x = Ok::<_, ()>(()); /// @@ -310,15 +311,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `option.map(_).unwrap_or(_)` or `option.map(_).unwrap_or_else(_)` or + /// ### What it does + /// Checks for usage of `option.map(_).unwrap_or(_)` or `option.map(_).unwrap_or_else(_)` or /// `result.map(_).unwrap_or_else(_)`. /// - /// **Why is this bad?** Readability, these can be written more concisely (resp.) as + /// ### Why is this bad? + /// Readability, these can be written more concisely (resp.) as /// `option.map_or(_, _)`, `option.map_or_else(_, _)` and `result.map_or_else(_, _)`. /// - /// **Known problems:** The order of the arguments is not in execution order + /// ### Known problems + /// The order of the arguments is not in execution order /// - /// **Examples:** + /// ### Examples /// ```rust /// # let x = Some(1); /// @@ -347,14 +351,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `_.map_or(None, _)`. + /// ### What it does + /// Checks for usage of `_.map_or(None, _)`. /// - /// **Why is this bad?** Readability, this can be written more concisely as + /// ### Why is this bad? + /// Readability, this can be written more concisely as /// `_.and_then(_)`. /// - /// **Known problems:** The order of the arguments is not in execution order. + /// ### Known problems + /// The order of the arguments is not in execution order. /// - /// **Example:** + /// ### Example /// ```rust /// # let opt = Some(1); /// @@ -370,15 +377,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `_.map_or(None, Some)`. + /// ### What it does + /// Checks for usage of `_.map_or(None, Some)`. /// - /// **Why is this bad?** Readability, this can be written more concisely as + /// ### Why is this bad? + /// Readability, this can be written more concisely as /// `_.ok()`. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// Bad: /// ```rust /// # let r: Result<u32, &str> = Ok(1); @@ -396,16 +402,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `_.and_then(|x| Some(y))`, `_.and_then(|x| Ok(y))` or + /// ### What it does + /// Checks for usage of `_.and_then(|x| Some(y))`, `_.and_then(|x| Ok(y))` or /// `_.or_else(|x| Err(y))`. /// - /// **Why is this bad?** Readability, this can be written more concisely as + /// ### Why is this bad? + /// Readability, this can be written more concisely as /// `_.map(|x| y)` or `_.map_err(|x| y)`. /// - /// **Known problems:** None - /// - /// **Example:** - /// + /// ### Example /// ```rust /// # fn opt() -> Option<&'static str> { Some("42") } /// # fn res() -> Result<&'static str, &'static str> { Ok("42") } @@ -429,14 +434,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `_.filter(_).next()`. + /// ### What it does + /// Checks for usage of `_.filter(_).next()`. /// - /// **Why is this bad?** Readability, this can be written more concisely as + /// ### Why is this bad? + /// Readability, this can be written more concisely as /// `_.find(_)`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let vec = vec![1]; /// vec.iter().filter(|x| **x == 0).next(); @@ -452,14 +457,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `_.skip_while(condition).next()`. + /// ### What it does + /// Checks for usage of `_.skip_while(condition).next()`. /// - /// **Why is this bad?** Readability, this can be written more concisely as + /// ### Why is this bad? + /// Readability, this can be written more concisely as /// `_.find(!condition)`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let vec = vec![1]; /// vec.iter().skip_while(|x| **x == 0).next(); @@ -475,14 +480,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `_.map(_).flatten(_)` on `Iterator` and `Option` + /// ### What it does + /// Checks for usage of `_.map(_).flatten(_)` on `Iterator` and `Option` /// - /// **Why is this bad?** Readability, this can be written more concisely as + /// ### Why is this bad? + /// Readability, this can be written more concisely as /// `_.flat_map(_)` /// - /// **Known problems:** - /// - /// **Example:** + /// ### Example /// ```rust /// let vec = vec![vec![1]]; /// @@ -498,15 +503,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `_.filter(_).map(_)` that can be written more simply + /// ### What it does + /// Checks for usage of `_.filter(_).map(_)` that can be written more simply /// as `filter_map(_)`. /// - /// **Why is this bad?** Redundant code in the `filter` and `map` operations is poor style and + /// ### Why is this bad? + /// Redundant code in the `filter` and `map` operations is poor style and /// less performant. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// Bad: /// ```rust /// (0_i32..10) @@ -524,15 +529,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `_.find(_).map(_)` that can be written more simply + /// ### What it does + /// Checks for usage of `_.find(_).map(_)` that can be written more simply /// as `find_map(_)`. /// - /// **Why is this bad?** Redundant code in the `find` and `map` operations is poor style and + /// ### Why is this bad? + /// Redundant code in the `find` and `map` operations is poor style and /// less performant. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// Bad: /// ```rust /// (0_i32..10) @@ -550,14 +555,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `_.filter_map(_).next()`. + /// ### What it does + /// Checks for usage of `_.filter_map(_).next()`. /// - /// **Why is this bad?** Readability, this can be written more concisely as + /// ### Why is this bad? + /// Readability, this can be written more concisely as /// `_.find_map(_)`. /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```rust /// (0..3).filter_map(|x| if x == 2 { Some(x) } else { None }).next(); /// ``` @@ -572,13 +577,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `flat_map(|x| x)`. + /// ### What it does + /// Checks for usage of `flat_map(|x| x)`. /// - /// **Why is this bad?** Readability, this can be written more concisely by using `flatten`. + /// ### Why is this bad? + /// Readability, this can be written more concisely by using `flatten`. /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```rust /// # let iter = vec![vec![0]].into_iter(); /// iter.flat_map(|x| x); @@ -594,16 +599,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for an iterator or string search (such as `find()`, + /// ### What it does + /// Checks for an iterator or string search (such as `find()`, /// `position()`, or `rposition()`) followed by a call to `is_some()` or `is_none()`. /// - /// **Why is this bad?** Readability, this can be written more concisely as: + /// ### Why is this bad? + /// Readability, this can be written more concisely as: /// * `_.any(_)`, or `_.contains(_)` for `is_some()`, /// * `!_.any(_)`, or `!_.contains(_)` for `is_none()`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let vec = vec![1]; /// vec.iter().find(|x| **x == 0).is_some(); @@ -623,15 +628,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `.chars().next()` on a `str` to check + /// ### What it does + /// Checks for usage of `.chars().next()` on a `str` to check /// if it starts with a given char. /// - /// **Why is this bad?** Readability, this can be written more concisely as + /// ### Why is this bad? + /// Readability, this can be written more concisely as /// `_.starts_with(_)`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let name = "foo"; /// if name.chars().next() == Some('_') {}; @@ -647,17 +652,20 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for calls to `.or(foo(..))`, `.unwrap_or(foo(..))`, + /// ### What it does + /// Checks for calls to `.or(foo(..))`, `.unwrap_or(foo(..))`, /// etc., and suggests to use `or_else`, `unwrap_or_else`, etc., or /// `unwrap_or_default` instead. /// - /// **Why is this bad?** The function will always be called and potentially + /// ### Why is this bad? + /// The function will always be called and potentially /// allocate an object acting as the default. /// - /// **Known problems:** If the function has side-effects, not calling it will + /// ### Known problems + /// If the function has side-effects, not calling it will /// change the semantic of the program, but you shouldn't rely on that anyway. /// - /// **Example:** + /// ### Example /// ```rust /// # let foo = Some(String::new()); /// foo.unwrap_or(String::new()); @@ -678,15 +686,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for calls to `.expect(&format!(...))`, `.expect(foo(..))`, + /// ### What it does + /// Checks for calls to `.expect(&format!(...))`, `.expect(foo(..))`, /// etc., and suggests to use `unwrap_or_else` instead /// - /// **Why is this bad?** The function will always be called. + /// ### Why is this bad? + /// The function will always be called. /// - /// **Known problems:** If the function has side-effects, not calling it will + /// ### Known problems + /// If the function has side-effects, not calling it will /// change the semantics of the program, but you shouldn't rely on that anyway. /// - /// **Example:** + /// ### Example /// ```rust /// # let foo = Some(String::new()); /// # let err_code = "418"; @@ -713,14 +724,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `.clone()` on a `Copy` type. + /// ### What it does + /// Checks for usage of `.clone()` on a `Copy` type. /// - /// **Why is this bad?** The only reason `Copy` types implement `Clone` is for + /// ### Why is this bad? + /// The only reason `Copy` types implement `Clone` is for /// generics, not for using the `clone` method on a concrete type. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// 42u64.clone(); /// ``` @@ -730,15 +741,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `.clone()` on a ref-counted pointer, + /// ### What it does + /// Checks for usage of `.clone()` on a ref-counted pointer, /// (`Rc`, `Arc`, `rc::Weak`, or `sync::Weak`), and suggests calling Clone via unified /// function syntax instead (e.g., `Rc::clone(foo)`). /// - /// **Why is this bad?** Calling '.clone()' on an Rc, Arc, or Weak + /// ### Why is this bad? + /// Calling '.clone()' on an Rc, Arc, or Weak /// can obscure the fact that only the pointer is being cloned, not the underlying /// data. /// - /// **Example:** + /// ### Example /// ```rust /// # use std::rc::Rc; /// let x = Rc::new(1); @@ -755,14 +768,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `.clone()` on an `&&T`. + /// ### What it does + /// Checks for usage of `.clone()` on an `&&T`. /// - /// **Why is this bad?** Cloning an `&&T` copies the inner `&T`, instead of + /// ### Why is this bad? + /// Cloning an `&&T` copies the inner `&T`, instead of /// cloning the underlying `T`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// fn main() { /// let x = vec![1]; @@ -777,16 +790,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `.to_string()` on an `&&T` where + /// ### What it does + /// Checks for usage of `.to_string()` on an `&&T` where /// `T` implements `ToString` directly (like `&&str` or `&&String`). /// - /// **Why is this bad?** This bypasses the specialized implementation of + /// ### Why is this bad? + /// This bypasses the specialized implementation of /// `ToString` and instead goes through the more expensive string formatting /// facilities. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// // Generic implementation for `T: Display` is used (slow) /// ["foo", "bar"].iter().map(|s| s.to_string()); @@ -800,14 +813,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `new` not returning a type that contains `Self`. + /// ### What it does + /// Checks for `new` not returning a type that contains `Self`. /// - /// **Why is this bad?** As a convention, `new` methods are used to make a new + /// ### Why is this bad? + /// As a convention, `new` methods are used to make a new /// instance of a type. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// In an impl block: /// ```rust /// # struct Foo; @@ -861,15 +874,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for string methods that receive a single-character + /// ### What it does + /// Checks for string methods that receive a single-character /// `str` as an argument, e.g., `_.split("x")`. /// - /// **Why is this bad?** Performing these methods using a `char` is faster than + /// ### Why is this bad? + /// Performing these methods using a `char` is faster than /// using a `str`. /// - /// **Known problems:** Does not catch multi-byte unicode characters. + /// ### Known problems + /// Does not catch multi-byte unicode characters. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// // Bad /// _.split("x"); @@ -882,14 +898,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for calling `.step_by(0)` on iterators which panics. + /// ### What it does + /// Checks for calling `.step_by(0)` on iterators which panics. /// - /// **Why is this bad?** This very much looks like an oversight. Use `panic!()` instead if you + /// ### Why is this bad? + /// This very much looks like an oversight. Use `panic!()` instead if you /// actually intend to panic. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,should_panic /// for x in (0..100).step_by(0) { /// //.. @@ -901,15 +917,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for indirect collection of populated `Option` + /// ### What it does + /// Checks for indirect collection of populated `Option` /// - /// **Why is this bad?** `Option` is like a collection of 0-1 things, so `flatten` + /// ### Why is this bad? + /// `Option` is like a collection of 0-1 things, so `flatten` /// automatically does this without suspicious-looking `unwrap` calls. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// let _ = std::iter::empty::<Option<i32>>().filter(Option::is_some).map(Option::unwrap); /// ``` @@ -923,16 +938,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for the use of `iter.nth(0)`. + /// ### What it does + /// Checks for the use of `iter.nth(0)`. /// - /// **Why is this bad?** `iter.next()` is equivalent to + /// ### Why is this bad? + /// `iter.next()` is equivalent to /// `iter.nth(0)`, as they both consume the next element, /// but is more readable. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// # use std::collections::HashSet; /// // Bad @@ -951,15 +965,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for use of `.iter().nth()` (and the related + /// ### What it does + /// Checks for use of `.iter().nth()` (and the related /// `.iter_mut().nth()`) on standard library types with O(1) element access. /// - /// **Why is this bad?** `.get()` and `.get_mut()` are more efficient and more + /// ### Why is this bad? + /// `.get()` and `.get_mut()` are more efficient and more /// readable. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let some_vec = vec![0, 1, 2, 3]; /// let bad_vec = some_vec.iter().nth(3); @@ -977,13 +991,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for use of `.skip(x).next()` on iterators. - /// - /// **Why is this bad?** `.nth(x)` is cleaner + /// ### What it does + /// Checks for use of `.skip(x).next()` on iterators. /// - /// **Known problems:** None. + /// ### Why is this bad? + /// `.nth(x)` is cleaner /// - /// **Example:** + /// ### Example /// ```rust /// let some_vec = vec![0, 1, 2, 3]; /// let bad_vec = some_vec.iter().skip(3).next(); @@ -1001,13 +1015,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for use of `.get().unwrap()` (or + /// ### What it does + /// Checks for use of `.get().unwrap()` (or /// `.get_mut().unwrap`) on a standard library type which implements `Index` /// - /// **Why is this bad?** Using the Index trait (`[]`) is more clear and more + /// ### Why is this bad? + /// Using the Index trait (`[]`) is more clear and more /// concise. /// - /// **Known problems:** Not a replacement for error handling: Using either + /// ### Known problems + /// Not a replacement for error handling: Using either /// `.unwrap()` or the Index trait (`[]`) carries the risk of causing a `panic` /// if the value being accessed is `None`. If the use of `.get().unwrap()` is a /// temporary placeholder for dealing with the `Option` type, then this does @@ -1016,7 +1033,7 @@ declare_clippy_lint! { /// is handled in a future refactor instead of using `.unwrap()` or the Index /// trait. /// - /// **Example:** + /// ### Example /// ```rust /// let mut some_vec = vec![0, 1, 2, 3]; /// let last = some_vec.get(3).unwrap(); @@ -1034,14 +1051,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for occurrences where one vector gets extended instead of append + /// ### What it does + /// Checks for occurrences where one vector gets extended instead of append /// - /// **Why is this bad?** Using `append` instead of `extend` is more concise and faster - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// Using `append` instead of `extend` is more concise and faster /// + /// ### Example /// ```rust /// let mut a = vec![1, 2, 3]; /// let mut b = vec![4, 5, 6]; @@ -1058,14 +1074,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for the use of `.extend(s.chars())` where s is a + /// ### What it does + /// Checks for the use of `.extend(s.chars())` where s is a /// `&str` or `String`. /// - /// **Why is this bad?** `.push_str(s)` is clearer + /// ### Why is this bad? + /// `.push_str(s)` is clearer /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let abc = "abc"; /// let def = String::from("def"); @@ -1087,14 +1103,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for the use of `.cloned().collect()` on slice to + /// ### What it does + /// Checks for the use of `.cloned().collect()` on slice to /// create a `Vec`. /// - /// **Why is this bad?** `.to_vec()` is clearer - /// - /// **Known problems:** None. + /// ### Why is this bad? + /// `.to_vec()` is clearer /// - /// **Example:** + /// ### Example /// ```rust /// let s = [1, 2, 3, 4, 5]; /// let s2: Vec<isize> = s[..].iter().cloned().collect(); @@ -1110,15 +1126,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `_.chars().last()` or + /// ### What it does + /// Checks for usage of `_.chars().last()` or /// `_.chars().next_back()` on a `str` to check if it ends with a given char. /// - /// **Why is this bad?** Readability, this can be written more concisely as + /// ### Why is this bad? + /// Readability, this can be written more concisely as /// `_.ends_with(_)`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let name = "_"; /// @@ -1134,14 +1150,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `.as_ref()` or `.as_mut()` where the + /// ### What it does + /// Checks for usage of `.as_ref()` or `.as_mut()` where the /// types before and after the call are the same. /// - /// **Why is this bad?** The call is unnecessary. - /// - /// **Known problems:** None. + /// ### Why is this bad? + /// The call is unnecessary. /// - /// **Example:** + /// ### Example /// ```rust /// # fn do_stuff(x: &[i32]) {} /// let x: &[i32] = &[1, 2, 3, 4, 5]; @@ -1159,15 +1175,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for using `fold` when a more succinct alternative exists. + /// ### What it does + /// Checks for using `fold` when a more succinct alternative exists. /// Specifically, this checks for `fold`s which could be replaced by `any`, `all`, /// `sum` or `product`. /// - /// **Why is this bad?** Readability. - /// - /// **Known problems:** None. + /// ### Why is this bad? + /// Readability. /// - /// **Example:** + /// ### Example /// ```rust /// let _ = (0..3).fold(false, |acc, x| acc || x > 2); /// ``` @@ -1181,16 +1197,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `filter_map` calls which could be replaced by `filter` or `map`. + /// ### What it does + /// Checks for `filter_map` calls which could be replaced by `filter` or `map`. /// More specifically it checks if the closure provided is only performing one of the /// filter or map operations and suggests the appropriate option. /// - /// **Why is this bad?** Complexity. The intent is also clearer if only a single + /// ### Why is this bad? + /// Complexity. The intent is also clearer if only a single /// operation is being performed. /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```rust /// let _ = (0..3).filter_map(|x| if x > 2 { Some(x) } else { None }); /// @@ -1210,17 +1226,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `into_iter` calls on references which should be replaced by `iter` + /// ### What it does + /// Checks for `into_iter` calls on references which should be replaced by `iter` /// or `iter_mut`. /// - /// **Why is this bad?** Readability. Calling `into_iter` on a reference will not move out its + /// ### Why is this bad? + /// Readability. Calling `into_iter` on a reference will not move out its /// content into the resulting iterator, which is confusing. It is better just call `iter` or /// `iter_mut` directly. /// - /// **Known problems:** None - /// - /// **Example:** - /// + /// ### Example /// ```rust /// // Bad /// let _ = (&vec![3, 4, 5]).into_iter(); @@ -1234,16 +1249,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for calls to `map` followed by a `count`. + /// ### What it does + /// Checks for calls to `map` followed by a `count`. /// - /// **Why is this bad?** It looks suspicious. Maybe `map` was confused with `filter`. + /// ### Why is this bad? + /// It looks suspicious. Maybe `map` was confused with `filter`. /// If the `map` call is intentional, this should be rewritten. Or, if you intend to /// drive the iterator to completion, you can just use `for_each` instead. /// - /// **Known problems:** None - /// - /// **Example:** - /// + /// ### Example /// ```rust /// let _ = (0..3).map(|x| x + 2).count(); /// ``` @@ -1253,16 +1267,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `MaybeUninit::uninit().assume_init()`. + /// ### What it does + /// Checks for `MaybeUninit::uninit().assume_init()`. /// - /// **Why is this bad?** For most types, this is undefined behavior. + /// ### Why is this bad? + /// For most types, this is undefined behavior. /// - /// **Known problems:** For now, we accept empty tuples and tuples / arrays + /// ### Known problems + /// For now, we accept empty tuples and tuples / arrays /// of `MaybeUninit`. There may be other types that allow uninitialized /// data, but those are not yet rigorously defined. /// - /// **Example:** - /// + /// ### Example /// ```rust /// // Beware the UB /// use std::mem::MaybeUninit; @@ -1285,12 +1301,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `.checked_add/sub(x).unwrap_or(MAX/MIN)`. + /// ### What it does + /// Checks for `.checked_add/sub(x).unwrap_or(MAX/MIN)`. /// - /// **Why is this bad?** These can be written simply with `saturating_add/sub` methods. - /// - /// **Example:** + /// ### Why is this bad? + /// These can be written simply with `saturating_add/sub` methods. /// + /// ### Example /// ```rust /// # let y: u32 = 0; /// # let x: u32 = 100; @@ -1312,14 +1329,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `offset(_)`, `wrapping_`{`add`, `sub`}, etc. on raw pointers to + /// ### What it does + /// Checks for `offset(_)`, `wrapping_`{`add`, `sub`}, etc. on raw pointers to /// zero-sized types /// - /// **Why is this bad?** This is a no-op, and likely unintended - /// - /// **Known problems:** None + /// ### Why is this bad? + /// This is a no-op, and likely unintended /// - /// **Example:** + /// ### Example /// ```rust /// unsafe { (&() as *const ()).offset(1) }; /// ``` @@ -1329,15 +1346,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `FileType::is_file()`. + /// ### What it does + /// Checks for `FileType::is_file()`. /// - /// **Why is this bad?** When people testing a file type with `FileType::is_file` + /// ### Why is this bad? + /// When people testing a file type with `FileType::is_file` /// they are testing whether a path is something they can get bytes from. But /// `is_file` doesn't cover special file types in unix-like systems, and doesn't cover /// symlink in windows. Using `!FileType::is_dir()` is a better way to that intention. /// - /// **Example:** - /// + /// ### Example /// ```rust /// # || { /// let metadata = std::fs::metadata("foo.txt")?; @@ -1369,14 +1387,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `_.as_ref().map(Deref::deref)` or it's aliases (such as String::as_str). + /// ### What it does + /// Checks for usage of `_.as_ref().map(Deref::deref)` or it's aliases (such as String::as_str). /// - /// **Why is this bad?** Readability, this can be written more concisely as + /// ### Why is this bad? + /// Readability, this can be written more concisely as /// `_.as_deref()`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let opt = Some("".to_string()); /// opt.as_ref().map(String::as_str) @@ -1394,13 +1412,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `iter().next()` on a Slice or an Array - /// - /// **Why is this bad?** These can be shortened into `.get()` + /// ### What it does + /// Checks for usage of `iter().next()` on a Slice or an Array /// - /// **Known problems:** None. + /// ### Why is this bad? + /// These can be shortened into `.get()` /// - /// **Example:** + /// ### Example /// ```rust /// # let a = [1, 2, 3]; /// # let b = vec![1, 2, 3]; @@ -1420,14 +1438,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Warns when using `push_str`/`insert_str` with a single-character string literal + /// ### What it does + /// Warns when using `push_str`/`insert_str` with a single-character string literal /// where `push`/`insert` with a `char` would work fine. /// - /// **Why is this bad?** It's less clear that we are pushing a single character. + /// ### Why is this bad? + /// It's less clear that we are pushing a single character. /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```rust /// let mut string = String::new(); /// string.insert_str(0, "R"); @@ -1445,7 +1463,8 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** As the counterpart to `or_fun_call`, this lint looks for unnecessary + /// ### What it does + /// As the counterpart to `or_fun_call`, this lint looks for unnecessary /// lazily evaluated closures on `Option` and `Result`. /// /// This lint suggests changing the following functions, when eager evaluation results in @@ -1456,13 +1475,14 @@ declare_clippy_lint! { /// - `get_or_insert_with` to `get_or_insert` /// - `ok_or_else` to `ok_or` /// - /// **Why is this bad?** Using eager evaluation is shorter and simpler in some cases. + /// ### Why is this bad? + /// Using eager evaluation is shorter and simpler in some cases. /// - /// **Known problems:** It is possible, but not recommended for `Deref` and `Index` to have + /// ### Known problems + /// It is possible, but not recommended for `Deref` and `Index` to have /// side effects. Eagerly evaluating them can change the semantics of the program. /// - /// **Example:** - /// + /// ### Example /// ```rust /// // example code where clippy issues a warning /// let opt: Option<u32> = None; @@ -1481,14 +1501,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `_.map(_).collect::<Result<(), _>()`. - /// - /// **Why is this bad?** Using `try_for_each` instead is more readable and idiomatic. - /// - /// **Known problems:** None + /// ### What it does + /// Checks for usage of `_.map(_).collect::<Result<(), _>()`. /// - /// **Example:** + /// ### Why is this bad? + /// Using `try_for_each` instead is more readable and idiomatic. /// + /// ### Example /// ```rust /// (0..3).map(|t| Err(t)).collect::<Result<(), _>>(); /// ``` @@ -1502,16 +1521,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `from_iter()` function calls on types that implement the `FromIterator` + /// ### What it does + /// Checks for `from_iter()` function calls on types that implement the `FromIterator` /// trait. /// - /// **Why is this bad?** It is recommended style to use collect. See + /// ### Why is this bad? + /// It is recommended style to use collect. See /// [FromIterator documentation](https://doc.rust-lang.org/std/iter/trait.FromIterator.html) /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// use std::iter::FromIterator; /// @@ -1535,15 +1553,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `inspect().for_each()`. + /// ### What it does + /// Checks for usage of `inspect().for_each()`. /// - /// **Why is this bad?** It is the same as performing the computation + /// ### Why is this bad? + /// It is the same as performing the computation /// inside `inspect` at the beginning of the closure in `for_each`. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// [1,2,3,4,5].iter() /// .inspect(|&x| println!("inspect the number: {}", x)) @@ -1565,14 +1582,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `filter_map(|x| x)`. - /// - /// **Why is this bad?** Readability, this can be written more concisely by using `flatten`. + /// ### What it does + /// Checks for usage of `filter_map(|x| x)`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// Readability, this can be written more concisely by using `flatten`. /// + /// ### Example /// ```rust /// # let iter = vec![Some(1)].into_iter(); /// iter.filter_map(|x| x); @@ -1588,14 +1604,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for instances of `map(f)` where `f` is the identity function. - /// - /// **Why is this bad?** It can be written more concisely without the call to `map`. + /// ### What it does + /// Checks for instances of `map(f)` where `f` is the identity function. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// It can be written more concisely without the call to `map`. /// + /// ### Example /// ```rust /// let x = [1, 2, 3]; /// let y: Vec<_> = x.iter().map(|x| x).map(|x| 2*x).collect(); @@ -1611,15 +1626,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for the use of `.bytes().nth()`. + /// ### What it does + /// Checks for the use of `.bytes().nth()`. /// - /// **Why is this bad?** `.as_bytes().get()` is more efficient and more + /// ### Why is this bad? + /// `.as_bytes().get()` is more efficient and more /// readable. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// // Bad /// let _ = "Hello".bytes().nth(3); @@ -1633,15 +1647,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for the usage of `_.to_owned()`, `vec.to_vec()`, or similar when calling `_.clone()` would be clearer. + /// ### What it does + /// Checks for the usage of `_.to_owned()`, `vec.to_vec()`, or similar when calling `_.clone()` would be clearer. /// - /// **Why is this bad?** These methods do the same thing as `_.clone()` but may be confusing as + /// ### Why is this bad? + /// These methods do the same thing as `_.clone()` but may be confusing as /// to why we are calling `to_vec` on something that is already a `Vec` or calling `to_owned` on something that is already owned. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// let a = vec![1, 2, 3]; /// let b = a.to_vec(); @@ -1659,15 +1672,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for the use of `.iter().count()`. + /// ### What it does + /// Checks for the use of `.iter().count()`. /// - /// **Why is this bad?** `.len()` is more efficient and more + /// ### Why is this bad? + /// `.len()` is more efficient and more /// readable. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// // Bad /// let some_vec = vec![0, 1, 2, 3]; @@ -1685,17 +1697,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for calls to [`splitn`] + /// ### What it does + /// Checks for calls to [`splitn`] /// (https://doc.rust-lang.org/std/primitive.str.html#method.splitn) and /// related functions with either zero or one splits. /// - /// **Why is this bad?** These calls don't actually split the value and are + /// ### Why is this bad? + /// These calls don't actually split the value and are /// likely to be intended as a different number. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// // Bad /// let s = ""; @@ -1715,14 +1726,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for manual implementations of `str::repeat` - /// - /// **Why is this bad?** These are both harder to read, as well as less performant. - /// - /// **Known problems:** None. + /// ### What it does + /// Checks for manual implementations of `str::repeat` /// - /// **Example:** + /// ### Why is this bad? + /// These are both harder to read, as well as less performant. /// + /// ### Example /// ```rust /// // Bad /// let x: String = std::iter::repeat('x').take(10).collect(); diff --git a/clippy_lints/src/minmax.rs b/clippy_lints/src/minmax.rs index ff3473b744e47..dc2dd45e4edb6 100644 --- a/clippy_lints/src/minmax.rs +++ b/clippy_lints/src/minmax.rs @@ -8,15 +8,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use std::cmp::Ordering; declare_clippy_lint! { - /// **What it does:** Checks for expressions where `std::cmp::min` and `max` are + /// ### What it does + /// Checks for expressions where `std::cmp::min` and `max` are /// used to clamp values, but switched so that the result is constant. /// - /// **Why is this bad?** This is in all probability not the intended outcome. At + /// ### Why is this bad? + /// This is in all probability not the intended outcome. At /// the least it hurts readability of the code. /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```ignore /// min(0, max(100, x)) /// ``` diff --git a/clippy_lints/src/misc.rs b/clippy_lints/src/misc.rs index 7cfce2e61cca5..c796abe9815a4 100644 --- a/clippy_lints/src/misc.rs +++ b/clippy_lints/src/misc.rs @@ -25,10 +25,12 @@ use clippy_utils::{ }; declare_clippy_lint! { - /// **What it does:** Checks for function arguments and let bindings denoted as + /// ### What it does + /// Checks for function arguments and let bindings denoted as /// `ref`. /// - /// **Why is this bad?** The `ref` declaration makes the function take an owned + /// ### Why is this bad? + /// The `ref` declaration makes the function take an owned /// value, but turns the argument into a reference (which means that the value /// is destroyed when exiting the function). This adds not much value: either /// take a reference type, or take an owned value and create references in the @@ -37,11 +39,12 @@ declare_clippy_lint! { /// For let bindings, `let x = &foo;` is preferred over `let ref x = foo`. The /// type of `x` is more obvious with the former. /// - /// **Known problems:** If the argument is dereferenced within the function, + /// ### Known problems + /// If the argument is dereferenced within the function, /// removing the `ref` will lead to errors. This can be fixed by removing the /// dereferences, e.g., changing `*x` to `x` within the function. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// // Bad /// fn foo(ref x: u8) -> bool { @@ -59,14 +62,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for comparisons to NaN. + /// ### What it does + /// Checks for comparisons to NaN. /// - /// **Why is this bad?** NaN does not compare meaningfully to anything – not + /// ### Why is this bad? + /// NaN does not compare meaningfully to anything – not /// even itself – so those comparisons are simply wrong. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let x = 1.0; /// @@ -82,18 +85,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for (in-)equality comparisons on floating-point + /// ### What it does + /// Checks for (in-)equality comparisons on floating-point /// values (apart from zero), except in functions called `*eq*` (which probably /// implement equality for a type involving floats). /// - /// **Why is this bad?** Floating point calculations are usually imprecise, so + /// ### Why is this bad? + /// Floating point calculations are usually imprecise, so /// asking if two values are *exactly* equal is asking for trouble. For a good /// guide on what to do, see [the floating point /// guide](http://www.floating-point-gui.de/errors/comparison). /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x = 1.2331f64; /// let y = 1.2332f64; @@ -115,16 +118,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for conversions to owned values just for the sake + /// ### What it does + /// Checks for conversions to owned values just for the sake /// of a comparison. /// - /// **Why is this bad?** The comparison can operate on a reference, so creating + /// ### Why is this bad? + /// The comparison can operate on a reference, so creating /// an owned value effectively throws it away directly afterwards, which is /// needlessly consuming code and heap space. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let x = "foo"; /// # let y = String::from("foo"); @@ -142,18 +145,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for getting the remainder of a division by one or minus + /// ### What it does + /// Checks for getting the remainder of a division by one or minus /// one. /// - /// **Why is this bad?** The result for a divisor of one can only ever be zero; for + /// ### Why is this bad? + /// The result for a divisor of one can only ever be zero; for /// minus one it can cause panic/overflow (if the left operand is the minimal value of /// the respective integer type) or results in zero. No one will write such code /// deliberately, unless trying to win an Underhanded Rust Contest. Even for that /// contest, it's probably a bad idea. Use something more underhanded. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let x = 1; /// let a = x % 1; @@ -165,17 +168,20 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for the use of bindings with a single leading + /// ### What it does + /// Checks for the use of bindings with a single leading /// underscore. /// - /// **Why is this bad?** A single leading underscore is usually used to indicate + /// ### Why is this bad? + /// A single leading underscore is usually used to indicate /// that a binding will not be used. Using such a binding breaks this /// expectation. /// - /// **Known problems:** The lint does not work properly with desugaring and + /// ### Known problems + /// The lint does not work properly with desugaring and /// macro, it has been allowed in the mean time. /// - /// **Example:** + /// ### Example /// ```rust /// let _x = 0; /// let y = _x + 1; // Here we are using `_x`, even though it has a leading @@ -187,17 +193,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for the use of short circuit boolean conditions as + /// ### What it does + /// Checks for the use of short circuit boolean conditions as /// a /// statement. /// - /// **Why is this bad?** Using a short circuit boolean condition as a statement + /// ### Why is this bad? + /// Using a short circuit boolean condition as a statement /// may hide the fact that the second part is executed or not depending on the /// outcome of the first part. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// f() && g(); // We should write `if f() { g(); }`. /// ``` @@ -207,15 +213,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Catch casts from `0` to some pointer type + /// ### What it does + /// Catch casts from `0` to some pointer type /// - /// **Why is this bad?** This generally means `null` and is better expressed as + /// ### Why is this bad? + /// This generally means `null` and is better expressed as /// {`std`, `core`}`::ptr::`{`null`, `null_mut`}. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// // Bad /// let a = 0 as *const u32; @@ -229,18 +234,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for (in-)equality comparisons on floating-point + /// ### What it does + /// Checks for (in-)equality comparisons on floating-point /// value and constant, except in functions called `*eq*` (which probably /// implement equality for a type involving floats). /// - /// **Why is this bad?** Floating point calculations are usually imprecise, so + /// ### Why is this bad? + /// Floating point calculations are usually imprecise, so /// asking if two values are *exactly* equal is asking for trouble. For a good /// guide on what to do, see [the floating point /// guide](http://www.floating-point-gui.de/errors/comparison). /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x: f64 = 1.0; /// const ONE: f64 = 1.00; diff --git a/clippy_lints/src/misc_early/mod.rs b/clippy_lints/src/misc_early/mod.rs index 050b6805b7c98..06fe967dafc40 100644 --- a/clippy_lints/src/misc_early/mod.rs +++ b/clippy_lints/src/misc_early/mod.rs @@ -18,14 +18,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::source_map::Span; declare_clippy_lint! { - /// **What it does:** Checks for structure field patterns bound to wildcards. + /// ### What it does + /// Checks for structure field patterns bound to wildcards. /// - /// **Why is this bad?** Using `..` instead is shorter and leaves the focus on + /// ### Why is this bad? + /// Using `..` instead is shorter and leaves the focus on /// the fields that are actually bound. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # struct Foo { /// # a: i32, @@ -52,14 +52,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for function arguments having the similar names + /// ### What it does + /// Checks for function arguments having the similar names /// differing by an underscore. /// - /// **Why is this bad?** It affects code readability. - /// - /// **Known problems:** None. + /// ### Why is this bad? + /// It affects code readability. /// - /// **Example:** + /// ### Example /// ```rust /// // Bad /// fn foo(a: i32, _a: i32) {} @@ -73,14 +73,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Detects expressions of the form `--x`. + /// ### What it does + /// Detects expressions of the form `--x`. /// - /// **Why is this bad?** It can mislead C/C++ programmers to think `x` was + /// ### Why is this bad? + /// It can mislead C/C++ programmers to think `x` was /// decremented. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let mut x = 3; /// --x; @@ -91,14 +91,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Warns on hexadecimal literals with mixed-case letter + /// ### What it does + /// Warns on hexadecimal literals with mixed-case letter /// digits. /// - /// **Why is this bad?** It looks confusing. + /// ### Why is this bad? + /// It looks confusing. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// // Bad /// let y = 0x1a9BAcD; @@ -112,14 +112,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Warns if literal suffixes are not separated by an + /// ### What it does + /// Warns if literal suffixes are not separated by an /// underscore. /// - /// **Why is this bad?** It is much less readable. - /// - /// **Known problems:** None. + /// ### Why is this bad? + /// It is much less readable. /// - /// **Example:** + /// ### Example /// ```rust /// // Bad /// let y = 123832i32; @@ -133,17 +133,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Warns if an integral constant literal starts with `0`. + /// ### What it does + /// Warns if an integral constant literal starts with `0`. /// - /// **Why is this bad?** In some languages (including the infamous C language + /// ### Why is this bad? + /// In some languages (including the infamous C language /// and most of its /// family), this marks an octal constant. In Rust however, this is a decimal /// constant. This could /// be confusing for both the writer and a reader of the constant. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// /// In Rust: /// ```rust @@ -171,13 +171,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Warns if a generic shadows a built-in type. - /// - /// **Why is this bad?** This gives surprising type errors. + /// ### What it does + /// Warns if a generic shadows a built-in type. /// - /// **Known problems:** None. + /// ### Why is this bad? + /// This gives surprising type errors. /// - /// **Example:** + /// ### Example /// /// ```ignore /// impl<u32> Foo<u32> { @@ -192,14 +192,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for patterns in the form `name @ _`. + /// ### What it does + /// Checks for patterns in the form `name @ _`. /// - /// **Why is this bad?** It's almost always more readable to just use direct + /// ### Why is this bad? + /// It's almost always more readable to just use direct /// bindings. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let v = Some("abc"); /// @@ -221,19 +221,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for tuple patterns with a wildcard + /// ### What it does + /// Checks for tuple patterns with a wildcard /// pattern (`_`) is next to a rest pattern (`..`). /// /// _NOTE_: While `_, ..` means there is at least one element left, `..` /// means there are 0 or more elements left. This can make a difference /// when refactoring, but shouldn't result in errors in the refactored code, /// since the wildcard pattern isn't used anyway. - /// **Why is this bad?** The wildcard pattern is unneeded as the rest pattern + /// ### Why is this bad? + /// The wildcard pattern is unneeded as the rest pattern /// can match that element as well. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # struct TupleStruct(u32, u32, u32); /// # let t = TupleStruct(1, 2, 3); diff --git a/clippy_lints/src/missing_const_for_fn.rs b/clippy_lints/src/missing_const_for_fn.rs index 59cbc481ed42e..5b2584d43a130 100644 --- a/clippy_lints/src/missing_const_for_fn.rs +++ b/clippy_lints/src/missing_const_for_fn.rs @@ -13,16 +13,13 @@ use rustc_span::Span; use rustc_typeck::hir_ty_to_ty; declare_clippy_lint! { - /// **What it does:** - /// + /// ### What it does /// Suggests the use of `const` in functions and methods where possible. /// - /// **Why is this bad?** - /// + /// ### Why is this bad? /// Not having the function const prevents callers of the function from being const as well. /// - /// **Known problems:** - /// + /// ### Known problems /// Const functions are currently still being worked on, with some features only being available /// on nightly. This lint does not consider all edge cases currently and the suggestions may be /// incorrect if you are using this lint on stable. @@ -42,8 +39,7 @@ declare_clippy_lint! { /// can't be const as it calls a non-const function. Making `a` const and running Clippy again, /// will suggest to make `b` const, too. /// - /// **Example:** - /// + /// ### Example /// ```rust /// # struct Foo { /// # random_number: usize, diff --git a/clippy_lints/src/missing_doc.rs b/clippy_lints/src/missing_doc.rs index ec1572c26c262..aeed826890293 100644 --- a/clippy_lints/src/missing_doc.rs +++ b/clippy_lints/src/missing_doc.rs @@ -17,15 +17,15 @@ use rustc_span::source_map::Span; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Warns if there is missing doc for any documentable item + /// ### What it does + /// Warns if there is missing doc for any documentable item /// (public or private). /// - /// **Why is this bad?** Doc is good. *rustc* has a `MISSING_DOCS` + /// ### Why is this bad? + /// Doc is good. *rustc* has a `MISSING_DOCS` /// allowed-by-default lint for /// public members, but has no way to enforce documentation of private items. /// This lint fixes that. - /// - /// **Known problems:** None. pub MISSING_DOCS_IN_PRIVATE_ITEMS, restriction, "detects missing documentation for public and private members" diff --git a/clippy_lints/src/missing_enforced_import_rename.rs b/clippy_lints/src/missing_enforced_import_rename.rs index 59565350f7296..9d27870321cac 100644 --- a/clippy_lints/src/missing_enforced_import_rename.rs +++ b/clippy_lints/src/missing_enforced_import_rename.rs @@ -10,17 +10,16 @@ use rustc_span::Symbol; use crate::utils::conf::Rename; declare_clippy_lint! { - /// **What it does:** Checks for imports that do not rename the item as specified + /// ### What it does + /// Checks for imports that do not rename the item as specified /// in the `enforce-import-renames` config option. /// - /// **Why is this bad?** Consistency is important, if a project has defined import + /// ### Why is this bad? + /// Consistency is important, if a project has defined import /// renames they should be followed. More practically, some item names are too /// vague outside of their defining scope this can enforce a more meaningful naming. /// - /// **Known problems:** None - /// - /// **Example:** - /// + /// ### Example /// An example clippy.toml configuration: /// ```toml /// # clippy.toml diff --git a/clippy_lints/src/missing_inline.rs b/clippy_lints/src/missing_inline.rs index 041fe64a1a978..be5b4b4006ffd 100644 --- a/clippy_lints/src/missing_inline.rs +++ b/clippy_lints/src/missing_inline.rs @@ -7,10 +7,12 @@ use rustc_span::source_map::Span; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** it lints if an exported function, method, trait method with default impl, + /// ### What it does + /// it lints if an exported function, method, trait method with default impl, /// or trait method impl is not `#[inline]`. /// - /// **Why is this bad?** In general, it is not. Functions can be inlined across + /// ### Why is this bad? + /// In general, it is not. Functions can be inlined across /// crates when that's profitable as long as any form of LTO is used. When LTO is disabled, /// functions that are not `#[inline]` cannot be inlined across crates. Certain types of crates /// might intend for most of the methods in their public API to be able to be inlined across @@ -18,9 +20,7 @@ declare_clippy_lint! { /// sense. It allows the crate to require all exported methods to be `#[inline]` by default, and /// then opt out for specific methods where this might not make sense. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// pub fn foo() {} // missing #[inline] /// fn ok() {} // ok diff --git a/clippy_lints/src/modulo_arithmetic.rs b/clippy_lints/src/modulo_arithmetic.rs index 1414fdc1b114d..2d14943b56c95 100644 --- a/clippy_lints/src/modulo_arithmetic.rs +++ b/clippy_lints/src/modulo_arithmetic.rs @@ -9,18 +9,18 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use std::fmt::Display; declare_clippy_lint! { - /// **What it does:** Checks for modulo arithmetic. + /// ### What it does + /// Checks for modulo arithmetic. /// - /// **Why is this bad?** The results of modulo (%) operation might differ + /// ### Why is this bad? + /// The results of modulo (%) operation might differ /// depending on the language, when negative numbers are involved. /// If you interop with different languages it might be beneficial /// to double check all places that use modulo arithmetic. /// /// For example, in Rust `17 % -3 = 2`, but in Python `17 % -3 = -1`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x = -17 % 3; /// ``` diff --git a/clippy_lints/src/multiple_crate_versions.rs b/clippy_lints/src/multiple_crate_versions.rs index f5ce3e325512d..1c61970fdc8bb 100644 --- a/clippy_lints/src/multiple_crate_versions.rs +++ b/clippy_lints/src/multiple_crate_versions.rs @@ -13,17 +13,20 @@ use if_chain::if_chain; use itertools::Itertools; declare_clippy_lint! { - /// **What it does:** Checks to see if multiple versions of a crate are being + /// ### What it does + /// Checks to see if multiple versions of a crate are being /// used. /// - /// **Why is this bad?** This bloats the size of targets, and can lead to + /// ### Why is this bad? + /// This bloats the size of targets, and can lead to /// confusing error messages when structs or traits are used interchangeably /// between different versions of a crate. /// - /// **Known problems:** Because this can be caused purely by the dependencies + /// ### Known problems + /// Because this can be caused purely by the dependencies /// themselves, it's not always possible to fix this issue. /// - /// **Example:** + /// ### Example /// ```toml /// # This will pull in both winapi v0.3.x and v0.2.x, triggering a warning. /// [dependencies] diff --git a/clippy_lints/src/mut_key.rs b/clippy_lints/src/mut_key.rs index 68f7cdf6ea0b3..2c7681c45a462 100644 --- a/clippy_lints/src/mut_key.rs +++ b/clippy_lints/src/mut_key.rs @@ -10,18 +10,21 @@ use rustc_span::symbol::sym; use std::iter; declare_clippy_lint! { - /// **What it does:** Checks for sets/maps with mutable key types. + /// ### What it does + /// Checks for sets/maps with mutable key types. /// - /// **Why is this bad?** All of `HashMap`, `HashSet`, `BTreeMap` and + /// ### Why is this bad? + /// All of `HashMap`, `HashSet`, `BTreeMap` and /// `BtreeSet` rely on either the hash or the order of keys be unchanging, /// so having types with interior mutability is a bad idea. /// - /// **Known problems:** It's correct to use a struct, that contains interior mutability + /// ### Known problems + /// It's correct to use a struct, that contains interior mutability /// as a key, when its `Hash` implementation doesn't access any of the interior mutable types. /// However, this lint is unable to recognize this, so it causes a false positive in theses cases. /// The `bytes` crate is a great example of this. /// - /// **Example:** + /// ### Example /// ```rust /// use std::cmp::{PartialEq, Eq}; /// use std::collections::HashSet; diff --git a/clippy_lints/src/mut_mut.rs b/clippy_lints/src/mut_mut.rs index 4b9c51d0c16cc..d5032c5ba7f29 100644 --- a/clippy_lints/src/mut_mut.rs +++ b/clippy_lints/src/mut_mut.rs @@ -9,15 +9,15 @@ use rustc_middle::ty; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for instances of `mut mut` references. + /// ### What it does + /// Checks for instances of `mut mut` references. /// - /// **Why is this bad?** Multiple `mut`s don't add anything meaningful to the + /// ### Why is this bad? + /// Multiple `mut`s don't add anything meaningful to the /// source. This is either a copy'n'paste error, or it shows a fundamental /// misunderstanding of references. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let mut y = 1; /// let x = &mut &mut y; diff --git a/clippy_lints/src/mut_mutex_lock.rs b/clippy_lints/src/mut_mutex_lock.rs index b9ba74c7d0252..85e870632a5ca 100644 --- a/clippy_lints/src/mut_mutex_lock.rs +++ b/clippy_lints/src/mut_mutex_lock.rs @@ -8,17 +8,16 @@ use rustc_middle::ty; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for `&mut Mutex::lock` calls + /// ### What it does + /// Checks for `&mut Mutex::lock` calls /// - /// **Why is this bad?** `Mutex::lock` is less efficient than + /// ### Why is this bad? + /// `Mutex::lock` is less efficient than /// calling `Mutex::get_mut`. In addition you also have a statically /// guarantee that the mutex isn't locked, instead of just a runtime /// guarantee. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// use std::sync::{Arc, Mutex}; /// diff --git a/clippy_lints/src/mut_reference.rs b/clippy_lints/src/mut_reference.rs index 6efe8ffcde036..8d5d7951fc532 100644 --- a/clippy_lints/src/mut_reference.rs +++ b/clippy_lints/src/mut_reference.rs @@ -7,15 +7,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use std::iter; declare_clippy_lint! { - /// **What it does:** Detects passing a mutable reference to a function that only + /// ### What it does + /// Detects passing a mutable reference to a function that only /// requires an immutable reference. /// - /// **Why is this bad?** The mutable reference rules out all other references to + /// ### Why is this bad? + /// The mutable reference rules out all other references to /// the value. Also the code misleads about the intent of the call site. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// // Bad /// my_vec.push(&mut value) diff --git a/clippy_lints/src/mutable_debug_assertion.rs b/clippy_lints/src/mutable_debug_assertion.rs index 81bf853300fe5..ee50891cc3103 100644 --- a/clippy_lints/src/mutable_debug_assertion.rs +++ b/clippy_lints/src/mutable_debug_assertion.rs @@ -9,17 +9,17 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** Checks for function/method calls with a mutable + /// ### What it does + /// Checks for function/method calls with a mutable /// parameter in `debug_assert!`, `debug_assert_eq!` and `debug_assert_ne!` macros. /// - /// **Why is this bad?** In release builds `debug_assert!` macros are optimized out by the + /// ### Why is this bad? + /// In release builds `debug_assert!` macros are optimized out by the /// compiler. /// Therefore mutating something in a `debug_assert!` macro results in different behaviour /// between a release and debug build. /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// debug_assert_eq!(vec![3].pop(), Some(3)); /// // or diff --git a/clippy_lints/src/mutex_atomic.rs b/clippy_lints/src/mutex_atomic.rs index 354e2c3fb7480..436ceec6cfa0b 100644 --- a/clippy_lints/src/mutex_atomic.rs +++ b/clippy_lints/src/mutex_atomic.rs @@ -10,17 +10,20 @@ use rustc_middle::ty::{self, Ty}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for usages of `Mutex<X>` where an atomic will do. + /// ### What it does + /// Checks for usages of `Mutex<X>` where an atomic will do. /// - /// **Why is this bad?** Using a mutex just to make access to a plain bool or + /// ### Why is this bad? + /// Using a mutex just to make access to a plain bool or /// reference sequential is shooting flies with cannons. /// `std::sync::atomic::AtomicBool` and `std::sync::atomic::AtomicPtr` are leaner and /// faster. /// - /// **Known problems:** This lint cannot detect if the mutex is actually used + /// ### Known problems + /// This lint cannot detect if the mutex is actually used /// for waiting before a critical section. /// - /// **Example:** + /// ### Example /// ```rust /// # let y = true; /// @@ -38,17 +41,20 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usages of `Mutex<X>` where `X` is an integral + /// ### What it does + /// Checks for usages of `Mutex<X>` where `X` is an integral /// type. /// - /// **Why is this bad?** Using a mutex just to make access to a plain integer + /// ### Why is this bad? + /// Using a mutex just to make access to a plain integer /// sequential is /// shooting flies with cannons. `std::sync::atomic::AtomicUsize` is leaner and faster. /// - /// **Known problems:** This lint cannot detect if the mutex is actually used + /// ### Known problems + /// This lint cannot detect if the mutex is actually used /// for waiting before a critical section. /// - /// **Example:** + /// ### Example /// ```rust /// # use std::sync::Mutex; /// let x = Mutex::new(0usize); diff --git a/clippy_lints/src/needless_arbitrary_self_type.rs b/clippy_lints/src/needless_arbitrary_self_type.rs index fe3c4455be5e2..9a3d9383cd98c 100644 --- a/clippy_lints/src/needless_arbitrary_self_type.rs +++ b/clippy_lints/src/needless_arbitrary_self_type.rs @@ -9,13 +9,13 @@ use rustc_span::symbol::kw; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** The lint checks for `self` in fn parameters that + /// ### What it does + /// The lint checks for `self` in fn parameters that /// specify the `Self`-type explicitly - /// **Why is this bad?** Increases the amount and decreases the readability of code + /// ### Why is this bad? + /// Increases the amount and decreases the readability of code /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```rust /// enum ValType { /// I32, diff --git a/clippy_lints/src/needless_bitwise_bool.rs b/clippy_lints/src/needless_bitwise_bool.rs index b30bfbd429443..203da29cb9170 100644 --- a/clippy_lints/src/needless_bitwise_bool.rs +++ b/clippy_lints/src/needless_bitwise_bool.rs @@ -9,20 +9,19 @@ use rustc_middle::ty; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// Checks for uses of bitwise and/or operators between booleans, where performance may be improved by using /// a lazy and. /// - /// **Why is this bad?** + /// ### Why is this bad? /// The bitwise operators do not support short-circuiting, so it may hinder code performance. /// Additionally, boolean logic "masked" as bitwise logic is not caught by lints like `unnecessary_fold` /// - /// **Known problems:** + /// ### Known problems /// This lint evaluates only when the right side is determined to have no side effects. At this time, that /// determination is quite conservative. /// - /// **Example:** - /// + /// ### Example /// ```rust /// let (x,y) = (true, false); /// if x & !y {} // where both x and y are booleans diff --git a/clippy_lints/src/needless_bool.rs b/clippy_lints/src/needless_bool.rs index 780690548e52b..36f2829a5b94e 100644 --- a/clippy_lints/src/needless_bool.rs +++ b/clippy_lints/src/needless_bool.rs @@ -15,17 +15,20 @@ use rustc_span::source_map::Spanned; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** Checks for expressions of the form `if c { true } else { + /// ### What it does + /// Checks for expressions of the form `if c { true } else { /// false }` (or vice versa) and suggests using the condition directly. /// - /// **Why is this bad?** Redundant code. + /// ### Why is this bad? + /// Redundant code. /// - /// **Known problems:** Maybe false positives: Sometimes, the two branches are + /// ### Known problems + /// Maybe false positives: Sometimes, the two branches are /// painstakingly documented (which we, of course, do not detect), so they *may* /// have some value. Even then, the documentation can be rewritten to match the /// shorter code. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// if x { /// false @@ -43,15 +46,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for expressions of the form `x == true`, + /// ### What it does + /// Checks for expressions of the form `x == true`, /// `x != true` and order comparisons such as `x < true` (or vice versa) and /// suggest using the variable directly. /// - /// **Why is this bad?** Unnecessary code. + /// ### Why is this bad? + /// Unnecessary code. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// if x == true {} /// if y == false {} diff --git a/clippy_lints/src/needless_borrow.rs b/clippy_lints/src/needless_borrow.rs index dd1dfa2bdfbcf..3f0b23ee4d3e4 100644 --- a/clippy_lints/src/needless_borrow.rs +++ b/clippy_lints/src/needless_borrow.rs @@ -17,15 +17,15 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** Checks for address of operations (`&`) that are going to + /// ### What it does + /// Checks for address of operations (`&`) that are going to /// be dereferenced immediately by the compiler. /// - /// **Why is this bad?** Suggests that the receiver of the expression borrows + /// ### Why is this bad? + /// Suggests that the receiver of the expression borrows /// the expression. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// // Bad /// let x: &i32 = &&&&&&5; @@ -39,13 +39,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `ref` bindings which create a reference to a reference. - /// - /// **Why is this bad?** The address-of operator at the use site is clearer about the need for a reference. + /// ### What it does + /// Checks for `ref` bindings which create a reference to a reference. /// - /// **Known problems:** None. + /// ### Why is this bad? + /// The address-of operator at the use site is clearer about the need for a reference. /// - /// **Example:** + /// ### Example /// ```rust /// // Bad /// let x = Some(""); diff --git a/clippy_lints/src/needless_borrowed_ref.rs b/clippy_lints/src/needless_borrowed_ref.rs index 0e976b130ebf1..36879eda7c003 100644 --- a/clippy_lints/src/needless_borrowed_ref.rs +++ b/clippy_lints/src/needless_borrowed_ref.rs @@ -7,12 +7,15 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for bindings that destructure a reference and borrow the inner + /// ### What it does + /// Checks for bindings that destructure a reference and borrow the inner /// value with `&ref`. /// - /// **Why is this bad?** This pattern has no effect in almost all cases. + /// ### Why is this bad? + /// This pattern has no effect in almost all cases. /// - /// **Known problems:** In some cases, `&ref` is needed to avoid a lifetime mismatch error. + /// ### Known problems + /// In some cases, `&ref` is needed to avoid a lifetime mismatch error. /// Example: /// ```rust /// fn foo(a: &Option<String>, b: &Option<String>) { @@ -23,7 +26,7 @@ declare_clippy_lint! { /// } /// ``` /// - /// **Example:** + /// ### Example /// Bad: /// ```rust /// let mut v = Vec::<String>::new(); diff --git a/clippy_lints/src/needless_continue.rs b/clippy_lints/src/needless_continue.rs index 1d19413e0d013..5088b8bb0d368 100644 --- a/clippy_lints/src/needless_continue.rs +++ b/clippy_lints/src/needless_continue.rs @@ -42,20 +42,20 @@ use rustc_span::source_map::{original_sp, DUMMY_SP}; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** The lint checks for `if`-statements appearing in loops + /// ### What it does + /// The lint checks for `if`-statements appearing in loops /// that contain a `continue` statement in either their main blocks or their /// `else`-blocks, when omitting the `else`-block possibly with some /// rearrangement of code can make the code easier to understand. /// - /// **Why is this bad?** Having explicit `else` blocks for `if` statements + /// ### Why is this bad? + /// Having explicit `else` blocks for `if` statements /// containing `continue` in their THEN branch adds unnecessary branching and /// nesting to the code. Having an else block containing just `continue` can /// also be better written by grouping the statements following the whole `if` /// statement within the THEN block and omitting the else block completely. /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```rust /// # fn condition() -> bool { false } /// # fn update_condition() {} diff --git a/clippy_lints/src/needless_for_each.rs b/clippy_lints/src/needless_for_each.rs index a723a472a25fe..d9aa42fe8eeb6 100644 --- a/clippy_lints/src/needless_for_each.rs +++ b/clippy_lints/src/needless_for_each.rs @@ -16,18 +16,17 @@ use clippy_utils::source::snippet_with_applicability; use clippy_utils::ty::has_iter_method; declare_clippy_lint! { - /// **What it does:** Checks for usage of `for_each` that would be more simply written as a + /// ### What it does + /// Checks for usage of `for_each` that would be more simply written as a /// `for` loop. /// - /// **Why is this bad?** `for_each` may be used after applying iterator transformers like + /// ### Why is this bad? + /// `for_each` may be used after applying iterator transformers like /// `filter` for better readability and performance. It may also be used to fit a simple /// operation on one line. /// But when none of these apply, a simple `for` loop is more idiomatic. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// let v = vec![0, 1, 2]; /// v.iter().for_each(|elem| { diff --git a/clippy_lints/src/needless_pass_by_value.rs b/clippy_lints/src/needless_pass_by_value.rs index 283b1847b6c99..03eeb54d8d1c2 100644 --- a/clippy_lints/src/needless_pass_by_value.rs +++ b/clippy_lints/src/needless_pass_by_value.rs @@ -24,20 +24,22 @@ use rustc_typeck::expr_use_visitor as euv; use std::borrow::Cow; declare_clippy_lint! { - /// **What it does:** Checks for functions taking arguments by value, but not + /// ### What it does + /// Checks for functions taking arguments by value, but not /// consuming them in its /// body. /// - /// **Why is this bad?** Taking arguments by reference is more flexible and can + /// ### Why is this bad? + /// Taking arguments by reference is more flexible and can /// sometimes avoid /// unnecessary allocations. /// - /// **Known problems:** + /// ### Known problems /// * This lint suggests taking an argument by reference, /// however sometimes it is better to let users decide the argument type /// (by using `Borrow` trait, for example), depending on how the function is used. /// - /// **Example:** + /// ### Example /// ```rust /// fn foo(v: Vec<i32>) { /// assert_eq!(v.len(), 42); diff --git a/clippy_lints/src/needless_question_mark.rs b/clippy_lints/src/needless_question_mark.rs index c64491c63e2dc..42e48336e1539 100644 --- a/clippy_lints/src/needless_question_mark.rs +++ b/clippy_lints/src/needless_question_mark.rs @@ -10,15 +10,13 @@ use rustc_middle::ty::TyS; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// Suggests alternatives for useless applications of `?` in terminating expressions /// - /// **Why is this bad?** There's no reason to use `?` to short-circuit when execution of the body will end there anyway. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// There's no reason to use `?` to short-circuit when execution of the body will end there anyway. /// + /// ### Example /// ```rust /// struct TO { /// magic: Option<usize>, diff --git a/clippy_lints/src/needless_update.rs b/clippy_lints/src/needless_update.rs index 8f325404deb45..2a33b7392caa4 100644 --- a/clippy_lints/src/needless_update.rs +++ b/clippy_lints/src/needless_update.rs @@ -5,18 +5,18 @@ use rustc_middle::ty; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for needlessly including a base struct on update + /// ### What it does + /// Checks for needlessly including a base struct on update /// when all fields are changed anyway. /// /// This lint is not applied to structs marked with /// [non_exhaustive](https://doc.rust-lang.org/reference/attributes/type_system.html). /// - /// **Why is this bad?** This will cost resources (because the base has to be + /// ### Why is this bad? + /// This will cost resources (because the base has to be /// somewhere), and make the code less readable. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # struct Point { /// # x: i32, diff --git a/clippy_lints/src/neg_cmp_op_on_partial_ord.rs b/clippy_lints/src/neg_cmp_op_on_partial_ord.rs index c824f6f54b5cc..6ad49b7060565 100644 --- a/clippy_lints/src/neg_cmp_op_on_partial_ord.rs +++ b/clippy_lints/src/neg_cmp_op_on_partial_ord.rs @@ -8,19 +8,16 @@ use rustc_middle::lint::in_external_macro; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// Checks for the usage of negated comparison operators on types which only implement /// `PartialOrd` (e.g., `f64`). /// - /// **Why is this bad?** + /// ### Why is this bad? /// These operators make it easy to forget that the underlying types actually allow not only three /// potential Orderings (Less, Equal, Greater) but also a fourth one (Uncomparable). This is /// especially easy to miss if the operator based comparison result is negated. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// use std::cmp::Ordering; /// diff --git a/clippy_lints/src/neg_multiply.rs b/clippy_lints/src/neg_multiply.rs index d5e1ea6d242de..fa36d8fb1b30f 100644 --- a/clippy_lints/src/neg_multiply.rs +++ b/clippy_lints/src/neg_multiply.rs @@ -7,13 +7,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::source_map::Span; declare_clippy_lint! { - /// **What it does:** Checks for multiplication by -1 as a form of negation. + /// ### What it does + /// Checks for multiplication by -1 as a form of negation. /// - /// **Why is this bad?** It's more readable to just negate. + /// ### Why is this bad? + /// It's more readable to just negate. /// - /// **Known problems:** This only catches integers (for now). + /// ### Known problems + /// This only catches integers (for now). /// - /// **Example:** + /// ### Example /// ```ignore /// x * -1 /// ``` diff --git a/clippy_lints/src/new_without_default.rs b/clippy_lints/src/new_without_default.rs index bc409dd6efb4d..5c63d245bf120 100644 --- a/clippy_lints/src/new_without_default.rs +++ b/clippy_lints/src/new_without_default.rs @@ -13,18 +13,17 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for types with a `fn new() -> Self` method and no + /// ### What it does + /// Checks for types with a `fn new() -> Self` method and no /// implementation of /// [`Default`](https://doc.rust-lang.org/std/default/trait.Default.html). /// - /// **Why is this bad?** The user might expect to be able to use + /// ### Why is this bad? + /// The user might expect to be able to use /// [`Default`](https://doc.rust-lang.org/std/default/trait.Default.html) as the /// type can be constructed without arguments. /// - /// **Known problems:** Hopefully none. - /// - /// **Example:** - /// + /// ### Example /// ```ignore /// struct Foo(Bar); /// diff --git a/clippy_lints/src/no_effect.rs b/clippy_lints/src/no_effect.rs index 910b05360925d..e07518b258687 100644 --- a/clippy_lints/src/no_effect.rs +++ b/clippy_lints/src/no_effect.rs @@ -9,15 +9,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use std::ops::Deref; declare_clippy_lint! { - /// **What it does:** Checks for statements which have no effect. + /// ### What it does + /// Checks for statements which have no effect. /// - /// **Why is this bad?** Similar to dead code, these statements are actually + /// ### Why is this bad? + /// Similar to dead code, these statements are actually /// executed. However, as they have no effect, all they do is make the code less /// readable. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// 0; /// ``` @@ -27,15 +27,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for expression statements that can be reduced to a + /// ### What it does + /// Checks for expression statements that can be reduced to a /// sub-expression. /// - /// **Why is this bad?** Expressions by themselves often have no side-effects. + /// ### Why is this bad? + /// Expressions by themselves often have no side-effects. /// Having such expressions reduces readability. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// compute_array()[0]; /// ``` diff --git a/clippy_lints/src/non_copy_const.rs b/clippy_lints/src/non_copy_const.rs index d775cd7c7f740..aa3067876ebf8 100644 --- a/clippy_lints/src/non_copy_const.rs +++ b/clippy_lints/src/non_copy_const.rs @@ -24,10 +24,12 @@ use rustc_typeck::hir_ty_to_ty; // FIXME: this is a correctness problem but there's no suitable // warn-by-default category. declare_clippy_lint! { - /// **What it does:** Checks for declaration of `const` items which is interior + /// ### What it does + /// Checks for declaration of `const` items which is interior /// mutable (e.g., contains a `Cell`, `Mutex`, `AtomicXxxx`, etc.). /// - /// **Why is this bad?** Consts are copied everywhere they are referenced, i.e., + /// ### Why is this bad? + /// Consts are copied everywhere they are referenced, i.e., /// every time you refer to the const a fresh instance of the `Cell` or `Mutex` /// or `AtomicXxxx` will be created, which defeats the whole purpose of using /// these types in the first place. @@ -35,7 +37,8 @@ declare_clippy_lint! { /// The `const` should better be replaced by a `static` item if a global /// variable is wanted, or replaced by a `const fn` if a constructor is wanted. /// - /// **Known problems:** A "non-constant" const item is a legacy way to supply an + /// ### Known problems + /// A "non-constant" const item is a legacy way to supply an /// initialized value to downstream `static` items (e.g., the /// `std::sync::ONCE_INIT` constant). In this case the use of `const` is legit, /// and this lint should be suppressed. @@ -52,7 +55,7 @@ declare_clippy_lint! { /// the interior mutable field is used or not. See issues /// [#5812](https://github.com/rust-lang/rust-clippy/issues/5812) and /// - /// **Example:** + /// ### Example /// ```rust /// use std::sync::atomic::{AtomicUsize, Ordering::SeqCst}; /// @@ -74,17 +77,20 @@ declare_clippy_lint! { // FIXME: this is a correctness problem but there's no suitable // warn-by-default category. declare_clippy_lint! { - /// **What it does:** Checks if `const` items which is interior mutable (e.g., + /// ### What it does + /// Checks if `const` items which is interior mutable (e.g., /// contains a `Cell`, `Mutex`, `AtomicXxxx`, etc.) has been borrowed directly. /// - /// **Why is this bad?** Consts are copied everywhere they are referenced, i.e., + /// ### Why is this bad? + /// Consts are copied everywhere they are referenced, i.e., /// every time you refer to the const a fresh instance of the `Cell` or `Mutex` /// or `AtomicXxxx` will be created, which defeats the whole purpose of using /// these types in the first place. /// /// The `const` value should be stored inside a `static` item. /// - /// **Known problems:** When an enum has variants with interior mutability, use of its non + /// ### Known problems + /// When an enum has variants with interior mutability, use of its non /// interior mutable variants can generate false positives. See issue /// [#3962](https://github.com/rust-lang/rust-clippy/issues/3962) /// @@ -93,7 +99,7 @@ declare_clippy_lint! { /// [#5812](https://github.com/rust-lang/rust-clippy/issues/5812) and /// [#3825](https://github.com/rust-lang/rust-clippy/issues/3825) /// - /// **Example:** + /// ### Example /// ```rust /// use std::sync::atomic::{AtomicUsize, Ordering::SeqCst}; /// const CONST_ATOM: AtomicUsize = AtomicUsize::new(12); diff --git a/clippy_lints/src/non_expressive_names.rs b/clippy_lints/src/non_expressive_names.rs index 7183a7c3858a8..dc55b103eb6f9 100644 --- a/clippy_lints/src/non_expressive_names.rs +++ b/clippy_lints/src/non_expressive_names.rs @@ -12,14 +12,14 @@ use rustc_span::symbol::{Ident, Symbol}; use std::cmp::Ordering; declare_clippy_lint! { - /// **What it does:** Checks for names that are very similar and thus confusing. + /// ### What it does + /// Checks for names that are very similar and thus confusing. /// - /// **Why is this bad?** It's hard to distinguish between names that differ only + /// ### Why is this bad? + /// It's hard to distinguish between names that differ only /// by a single character. /// - /// **Known problems:** None? - /// - /// **Example:** + /// ### Example /// ```ignore /// let checked_exp = something; /// let checked_expr = something_else; @@ -30,15 +30,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for too many variables whose name consists of a + /// ### What it does + /// Checks for too many variables whose name consists of a /// single character. /// - /// **Why is this bad?** It's hard to memorize what a variable means without a + /// ### Why is this bad? + /// It's hard to memorize what a variable means without a /// descriptive name. /// - /// **Known problems:** None? - /// - /// **Example:** + /// ### Example /// ```ignore /// let (a, b, c, d, e, f, g) = (...); /// ``` @@ -48,15 +48,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks if you have variables whose name consists of just + /// ### What it does + /// Checks if you have variables whose name consists of just /// underscores and digits. /// - /// **Why is this bad?** It's hard to memorize what a variable means without a + /// ### Why is this bad? + /// It's hard to memorize what a variable means without a /// descriptive name. /// - /// **Known problems:** None? - /// - /// **Example:** + /// ### Example /// ```rust /// let _1 = 1; /// let ___1 = 1; diff --git a/clippy_lints/src/non_octal_unix_permissions.rs b/clippy_lints/src/non_octal_unix_permissions.rs index a83daea97bf6b..3b74f69d3753a 100644 --- a/clippy_lints/src/non_octal_unix_permissions.rs +++ b/clippy_lints/src/non_octal_unix_permissions.rs @@ -9,15 +9,14 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for non-octal values used to set Unix file permissions. + /// ### What it does + /// Checks for non-octal values used to set Unix file permissions. /// - /// **Why is this bad?** They will be converted into octal, creating potentially + /// ### Why is this bad? + /// They will be converted into octal, creating potentially /// unintended file permissions. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust,ignore /// use std::fs::OpenOptions; /// use std::os::unix::fs::OpenOptionsExt; diff --git a/clippy_lints/src/nonstandard_macro_braces.rs b/clippy_lints/src/nonstandard_macro_braces.rs index 043e7fa30d6e9..dbe9cbe0ded83 100644 --- a/clippy_lints/src/nonstandard_macro_braces.rs +++ b/clippy_lints/src/nonstandard_macro_braces.rs @@ -13,16 +13,14 @@ use rustc_span::Span; use serde::{de, Deserialize}; declare_clippy_lint! { - /// **What it does:** Checks that common macros are used with consistent bracing. + /// ### What it does + /// Checks that common macros are used with consistent bracing. /// - /// **Why is this bad?** This is mostly a consistency lint although using () or [] + /// ### Why is this bad? + /// This is mostly a consistency lint although using () or [] /// doesn't give you a semicolon in item position, which can be unexpected. /// - /// **Known problems:** - /// None - /// - /// **Example:** - /// + /// ### Example /// ```rust /// vec!{1, 2, 3}; /// ``` diff --git a/clippy_lints/src/open_options.rs b/clippy_lints/src/open_options.rs index fded48038e39f..4064d94da2abf 100644 --- a/clippy_lints/src/open_options.rs +++ b/clippy_lints/src/open_options.rs @@ -8,15 +8,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::source_map::{Span, Spanned}; declare_clippy_lint! { - /// **What it does:** Checks for duplicate open options as well as combinations + /// ### What it does + /// Checks for duplicate open options as well as combinations /// that make no sense. /// - /// **Why is this bad?** In the best case, the code will be harder to read than + /// ### Why is this bad? + /// In the best case, the code will be harder to read than /// necessary. I don't know the worst case. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// use std::fs::OpenOptions; /// diff --git a/clippy_lints/src/option_env_unwrap.rs b/clippy_lints/src/option_env_unwrap.rs index b6f518661bdb1..d7306628030f6 100644 --- a/clippy_lints/src/option_env_unwrap.rs +++ b/clippy_lints/src/option_env_unwrap.rs @@ -7,17 +7,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for usage of `option_env!(...).unwrap()` and + /// ### What it does + /// Checks for usage of `option_env!(...).unwrap()` and /// suggests usage of the `env!` macro. /// - /// **Why is this bad?** Unwrapping the result of `option_env!` will panic + /// ### Why is this bad? + /// Unwrapping the result of `option_env!` will panic /// at run-time if the environment variable doesn't exist, whereas `env!` /// catches it at compile-time. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust,no_run /// let _ = option_env!("HOME").unwrap(); /// ``` diff --git a/clippy_lints/src/option_if_let_else.rs b/clippy_lints/src/option_if_let_else.rs index b2be35bdddb38..7aef3a5f34cf2 100644 --- a/clippy_lints/src/option_if_let_else.rs +++ b/clippy_lints/src/option_if_let_else.rs @@ -12,24 +12,23 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// Lints usage of `if let Some(v) = ... { y } else { x }` which is more /// idiomatically done with `Option::map_or` (if the else bit is a pure /// expression) or `Option::map_or_else` (if the else bit is an impure /// expression). /// - /// **Why is this bad?** + /// ### Why is this bad? /// Using the dedicated functions of the Option type is clearer and /// more concise than an `if let` expression. /// - /// **Known problems:** + /// ### Known problems /// This lint uses a deliberately conservative metric for checking /// if the inside of either body contains breaks or continues which will /// cause it to not suggest a fix if either block contains a loop with /// continues or breaks contained within the loop. /// - /// **Example:** - /// + /// ### Example /// ```rust /// # let optional: Option<u32> = Some(0); /// # fn do_complicated_function() -> u32 { 5 }; diff --git a/clippy_lints/src/overflow_check_conditional.rs b/clippy_lints/src/overflow_check_conditional.rs index e222782c2cc8c..34755afdb72f0 100644 --- a/clippy_lints/src/overflow_check_conditional.rs +++ b/clippy_lints/src/overflow_check_conditional.rs @@ -6,14 +6,14 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Detects classic underflow/overflow checks. + /// ### What it does + /// Detects classic underflow/overflow checks. /// - /// **Why is this bad?** Most classic C underflow/overflow checks will fail in + /// ### Why is this bad? + /// Most classic C underflow/overflow checks will fail in /// Rust. Users can use functions like `overflowing_*` and `wrapping_*` instead. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let a = 1; /// # let b = 2; diff --git a/clippy_lints/src/panic_in_result_fn.rs b/clippy_lints/src/panic_in_result_fn.rs index cef74d87e7c01..e2b6ba8e2d2f6 100644 --- a/clippy_lints/src/panic_in_result_fn.rs +++ b/clippy_lints/src/panic_in_result_fn.rs @@ -8,14 +8,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::{sym, Span}; declare_clippy_lint! { - /// **What it does:** Checks for usage of `panic!`, `unimplemented!`, `todo!`, `unreachable!` or assertions in a function of type result. + /// ### What it does + /// Checks for usage of `panic!`, `unimplemented!`, `todo!`, `unreachable!` or assertions in a function of type result. /// - /// **Why is this bad?** For some codebases, it is desirable for functions of type result to return an error instead of crashing. Hence panicking macros should be avoided. + /// ### Why is this bad? + /// For some codebases, it is desirable for functions of type result to return an error instead of crashing. Hence panicking macros should be avoided. /// - /// **Known problems:** Functions called from a function returning a `Result` may invoke a panicking macro. This is not checked. - /// - /// **Example:** + /// ### Known problems + /// Functions called from a function returning a `Result` may invoke a panicking macro. This is not checked. /// + /// ### Example /// ```rust /// fn result_with_panic() -> Result<bool, String> /// { diff --git a/clippy_lints/src/panic_unimplemented.rs b/clippy_lints/src/panic_unimplemented.rs index dc28874c16e67..d8d9081d6f172 100644 --- a/clippy_lints/src/panic_unimplemented.rs +++ b/clippy_lints/src/panic_unimplemented.rs @@ -7,13 +7,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** Checks for usage of `panic!`. + /// ### What it does + /// Checks for usage of `panic!`. /// - /// **Why is this bad?** `panic!` will stop the execution of the executable + /// ### Why is this bad? + /// `panic!` will stop the execution of the executable /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```no_run /// panic!("even with a good reason"); /// ``` @@ -23,13 +23,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `unimplemented!`. - /// - /// **Why is this bad?** This macro should not be present in production code + /// ### What it does + /// Checks for usage of `unimplemented!`. /// - /// **Known problems:** None. + /// ### Why is this bad? + /// This macro should not be present in production code /// - /// **Example:** + /// ### Example /// ```no_run /// unimplemented!(); /// ``` @@ -39,13 +39,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `todo!`. + /// ### What it does + /// Checks for usage of `todo!`. /// - /// **Why is this bad?** This macro should not be present in production code + /// ### Why is this bad? + /// This macro should not be present in production code /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```no_run /// todo!(); /// ``` @@ -55,13 +55,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `unreachable!`. - /// - /// **Why is this bad?** This macro can cause code to panic + /// ### What it does + /// Checks for usage of `unreachable!`. /// - /// **Known problems:** None. + /// ### Why is this bad? + /// This macro can cause code to panic /// - /// **Example:** + /// ### Example /// ```no_run /// unreachable!(); /// ``` diff --git a/clippy_lints/src/partialeq_ne_impl.rs b/clippy_lints/src/partialeq_ne_impl.rs index 1251ddd9a0273..4ec493e5f45e0 100644 --- a/clippy_lints/src/partialeq_ne_impl.rs +++ b/clippy_lints/src/partialeq_ne_impl.rs @@ -7,16 +7,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for manual re-implementations of `PartialEq::ne`. + /// ### What it does + /// Checks for manual re-implementations of `PartialEq::ne`. /// - /// **Why is this bad?** `PartialEq::ne` is required to always return the + /// ### Why is this bad? + /// `PartialEq::ne` is required to always return the /// negated result of `PartialEq::eq`, which is exactly what the default /// implementation does. Therefore, there should never be any need to /// re-implement it. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// struct Foo; /// diff --git a/clippy_lints/src/pass_by_ref_or_value.rs b/clippy_lints/src/pass_by_ref_or_value.rs index f6a704785598e..f738ac2541788 100644 --- a/clippy_lints/src/pass_by_ref_or_value.rs +++ b/clippy_lints/src/pass_by_ref_or_value.rs @@ -20,15 +20,18 @@ use rustc_target::spec::abi::Abi; use rustc_target::spec::Target; declare_clippy_lint! { - /// **What it does:** Checks for functions taking arguments by reference, where + /// ### What it does + /// Checks for functions taking arguments by reference, where /// the argument type is `Copy` and small enough to be more efficient to always /// pass by value. /// - /// **Why is this bad?** In many calling conventions instances of structs will + /// ### Why is this bad? + /// In many calling conventions instances of structs will /// be passed through registers if they fit into two or less general purpose /// registers. /// - /// **Known problems:** This lint is target register size dependent, it is + /// ### Known problems + /// This lint is target register size dependent, it is /// limited to 32-bit to try and reduce portability problems between 32 and /// 64-bit, but if you are compiling for 8 or 16-bit targets then the limit /// will be different. @@ -50,7 +53,7 @@ declare_clippy_lint! { /// that explains a real case in which this false positive /// led to an **undefined behaviour** introduced with unsafe code. /// - /// **Example:** + /// ### Example /// /// ```rust /// // Bad @@ -67,18 +70,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for functions taking arguments by value, where + /// ### What it does + /// Checks for functions taking arguments by value, where /// the argument type is `Copy` and large enough to be worth considering /// passing by reference. Does not trigger if the function is being exported, /// because that might induce API breakage, if the parameter is declared as mutable, /// or if the argument is a `self`. /// - /// **Why is this bad?** Arguments passed by value might result in an unnecessary + /// ### Why is this bad? + /// Arguments passed by value might result in an unnecessary /// shallow copy, taking up more space in the stack and requiring a call to /// `memcpy`, which can be expensive. /// - /// **Example:** - /// + /// ### Example /// ```rust /// #[derive(Clone, Copy)] /// struct TooLarge([u8; 2048]); diff --git a/clippy_lints/src/path_buf_push_overwrite.rs b/clippy_lints/src/path_buf_push_overwrite.rs index 0024592638104..3df7a72d29509 100644 --- a/clippy_lints/src/path_buf_push_overwrite.rs +++ b/clippy_lints/src/path_buf_push_overwrite.rs @@ -10,15 +10,15 @@ use rustc_span::symbol::sym; use std::path::{Component, Path}; declare_clippy_lint! { - /// **What it does:*** Checks for [push](https://doc.rust-lang.org/std/path/struct.PathBuf.html#method.push) + /// ### What it does + ///* Checks for [push](https://doc.rust-lang.org/std/path/struct.PathBuf.html#method.push) /// calls on `PathBuf` that can cause overwrites. /// - /// **Why is this bad?** Calling `push` with a root path at the start can overwrite the + /// ### Why is this bad? + /// Calling `push` with a root path at the start can overwrite the /// previous defined path. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// use std::path::PathBuf; /// diff --git a/clippy_lints/src/pattern_type_mismatch.rs b/clippy_lints/src/pattern_type_mismatch.rs index ea4065d371b81..4534f6e251659 100644 --- a/clippy_lints/src/pattern_type_mismatch.rs +++ b/clippy_lints/src/pattern_type_mismatch.rs @@ -13,7 +13,8 @@ use rustc_span::source_map::Span; use std::iter; declare_clippy_lint! { - /// **What it does:** Checks for patterns that aren't exact representations of the types + /// ### What it does + /// Checks for patterns that aren't exact representations of the types /// they are applied to. /// /// To satisfy this lint, you will have to adjust either the expression that is matched @@ -32,14 +33,12 @@ declare_clippy_lint! { /// this lint can still be used to highlight areas of interest and ensure a good understanding /// of ownership semantics. /// - /// **Why is this bad?** It isn't bad in general. But in some contexts it can be desirable + /// ### Why is this bad? + /// It isn't bad in general. But in some contexts it can be desirable /// because it increases ownership hints in the code, and will guard against some changes /// in ownership. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// This example shows the basic adjustments necessary to satisfy the lint. Note how /// the matched expression is explicitly dereferenced with `*` and the `inner` variable /// is bound to a shared borrow via `ref inner`. diff --git a/clippy_lints/src/precedence.rs b/clippy_lints/src/precedence.rs index 9cf00c953b95f..1a8da00d9d616 100644 --- a/clippy_lints/src/precedence.rs +++ b/clippy_lints/src/precedence.rs @@ -25,7 +25,8 @@ const ALLOWED_ODD_FUNCTIONS: [&str; 14] = [ ]; declare_clippy_lint! { - /// **What it does:** Checks for operations where precedence may be unclear + /// ### What it does + /// Checks for operations where precedence may be unclear /// and suggests to add parentheses. Currently it catches the following: /// * mixed usage of arithmetic and bit shifting/combining operators without /// parentheses @@ -33,13 +34,12 @@ declare_clippy_lint! { /// numeric literal) /// followed by a method call /// - /// **Why is this bad?** Not everyone knows the precedence of those operators by + /// ### Why is this bad? + /// Not everyone knows the precedence of those operators by /// heart, so expressions like these may trip others trying to reason about the /// code. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// * `1 << 2 + 3` equals 32, while `(1 << 2) + 3` equals 7 /// * `-1i32.abs()` equals -1, while `(-1i32).abs()` equals 1 pub PRECEDENCE, diff --git a/clippy_lints/src/ptr.rs b/clippy_lints/src/ptr.rs index b15447622a8af..c0d1f1eb6e65e 100644 --- a/clippy_lints/src/ptr.rs +++ b/clippy_lints/src/ptr.rs @@ -20,16 +20,19 @@ use rustc_span::{sym, MultiSpan}; use std::borrow::Cow; declare_clippy_lint! { - /// **What it does:** This lint checks for function arguments of type `&String` + /// ### What it does + /// This lint checks for function arguments of type `&String` /// or `&Vec` unless the references are mutable. It will also suggest you /// replace `.clone()` calls with the appropriate `.to_owned()`/`to_string()` /// calls. /// - /// **Why is this bad?** Requiring the argument to be of the specific size + /// ### Why is this bad? + /// Requiring the argument to be of the specific size /// makes the function less useful for no benefit; slices in the form of `&[T]` /// or `&str` usually suffice and can be obtained from other types, too. /// - /// **Known problems:** The lint does not follow data. So if you have an + /// ### Known problems + /// The lint does not follow data. So if you have an /// argument `x` and write `let y = x; y.clone()` the lint will not suggest /// changing that `.clone()` to `.to_owned()`. /// @@ -59,7 +62,7 @@ declare_clippy_lint! { /// other crates referencing it, of which you may not be aware. Carefully /// deprecate the function before applying the lint suggestions in this case. /// - /// **Example:** + /// ### Example /// ```ignore /// // Bad /// fn foo(&Vec<u32>) { .. } @@ -73,15 +76,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** This lint checks for equality comparisons with `ptr::null` + /// ### What it does + /// This lint checks for equality comparisons with `ptr::null` /// - /// **Why is this bad?** It's easier and more readable to use the inherent + /// ### Why is this bad? + /// It's easier and more readable to use the inherent /// `.is_null()` /// method instead /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// // Bad /// if x == ptr::null { @@ -99,19 +102,22 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** This lint checks for functions that take immutable + /// ### What it does + /// This lint checks for functions that take immutable /// references and return mutable ones. /// - /// **Why is this bad?** This is trivially unsound, as one can create two + /// ### Why is this bad? + /// This is trivially unsound, as one can create two /// mutable references from the same (immutable!) source. /// This [error](https://github.com/rust-lang/rust/issues/39465) /// actually lead to an interim Rust release 1.15.1. /// - /// **Known problems:** To be on the conservative side, if there's at least one + /// ### Known problems + /// To be on the conservative side, if there's at least one /// mutable reference with the output lifetime, this lint will not trigger. /// In practice, this case is unlikely anyway. /// - /// **Example:** + /// ### Example /// ```ignore /// fn foo(&Foo) -> &mut Bar { .. } /// ``` @@ -121,13 +127,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** This lint checks for invalid usages of `ptr::null`. - /// - /// **Why is this bad?** This causes undefined behavior. + /// ### What it does + /// This lint checks for invalid usages of `ptr::null`. /// - /// **Known problems:** None. + /// ### Why is this bad? + /// This causes undefined behavior. /// - /// **Example:** + /// ### Example /// ```ignore /// // Bad. Undefined behavior /// unsafe { std::slice::from_raw_parts(ptr::null(), 0); } diff --git a/clippy_lints/src/ptr_eq.rs b/clippy_lints/src/ptr_eq.rs index 77cfa3f6b176c..d6d7049fb61b2 100644 --- a/clippy_lints/src/ptr_eq.rs +++ b/clippy_lints/src/ptr_eq.rs @@ -8,16 +8,15 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Use `std::ptr::eq` when applicable + /// ### What it does + /// Use `std::ptr::eq` when applicable /// - /// **Why is this bad?** `ptr::eq` can be used to compare `&T` references + /// ### Why is this bad? + /// `ptr::eq` can be used to compare `&T` references /// (which coerce to `*const T` implicitly) by their address rather than /// comparing the values they point to. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// let a = &[1, 2, 3]; /// let b = &[1, 2, 3]; diff --git a/clippy_lints/src/ptr_offset_with_cast.rs b/clippy_lints/src/ptr_offset_with_cast.rs index afb198f49559a..f1975056ddc9b 100644 --- a/clippy_lints/src/ptr_offset_with_cast.rs +++ b/clippy_lints/src/ptr_offset_with_cast.rs @@ -8,15 +8,15 @@ use rustc_span::sym; use std::fmt; declare_clippy_lint! { - /// **What it does:** Checks for usage of the `offset` pointer method with a `usize` casted to an + /// ### What it does + /// Checks for usage of the `offset` pointer method with a `usize` casted to an /// `isize`. /// - /// **Why is this bad?** If we’re always increasing the pointer address, we can avoid the numeric + /// ### Why is this bad? + /// If we’re always increasing the pointer address, we can avoid the numeric /// cast by using the `add` method instead. /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```rust /// let vec = vec![b'a', b'b', b'c']; /// let ptr = vec.as_ptr(); diff --git a/clippy_lints/src/question_mark.rs b/clippy_lints/src/question_mark.rs index d66bac5224360..0e682c692c7a6 100644 --- a/clippy_lints/src/question_mark.rs +++ b/clippy_lints/src/question_mark.rs @@ -13,13 +13,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for expressions that could be replaced by the question mark operator. + /// ### What it does + /// Checks for expressions that could be replaced by the question mark operator. /// - /// **Why is this bad?** Question mark usage is more idiomatic. + /// ### Why is this bad? + /// Question mark usage is more idiomatic. /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```ignore /// if option.is_none() { /// return None; diff --git a/clippy_lints/src/ranges.rs b/clippy_lints/src/ranges.rs index b41c478c26615..0179bd48ee3cb 100644 --- a/clippy_lints/src/ranges.rs +++ b/clippy_lints/src/ranges.rs @@ -18,14 +18,14 @@ use rustc_span::symbol::Ident; use std::cmp::Ordering; declare_clippy_lint! { - /// **What it does:** Checks for zipping a collection with the range of + /// ### What it does + /// Checks for zipping a collection with the range of /// `0.._.len()`. /// - /// **Why is this bad?** The code is better expressed with `.enumerate()`. + /// ### Why is this bad? + /// The code is better expressed with `.enumerate()`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let x = vec![1]; /// x.iter().zip(0..x.len()); @@ -41,13 +41,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for exclusive ranges where 1 is added to the + /// ### What it does + /// Checks for exclusive ranges where 1 is added to the /// upper bound, e.g., `x..(y+1)`. /// - /// **Why is this bad?** The code is more readable with an inclusive range + /// ### Why is this bad? + /// The code is more readable with an inclusive range /// like `x..=y`. /// - /// **Known problems:** Will add unnecessary pair of parentheses when the + /// ### Known problems + /// Will add unnecessary pair of parentheses when the /// expression is not wrapped in a pair but starts with a opening parenthesis /// and ends with a closing one. /// I.e., `let _ = (f()+1)..(f()+1)` results in `let _ = ((f()+1)..=f())`. @@ -61,7 +64,7 @@ declare_clippy_lint! { /// `RangeBounds` trait /// ([#3307](https://github.com/rust-lang/rust-clippy/issues/3307)). /// - /// **Example:** + /// ### Example /// ```rust,ignore /// for x..(y+1) { .. } /// ``` @@ -75,18 +78,21 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for inclusive ranges where 1 is subtracted from + /// ### What it does + /// Checks for inclusive ranges where 1 is subtracted from /// the upper bound, e.g., `x..=(y-1)`. /// - /// **Why is this bad?** The code is more readable with an exclusive range + /// ### Why is this bad? + /// The code is more readable with an exclusive range /// like `x..y`. /// - /// **Known problems:** This will cause a warning that cannot be fixed if + /// ### Known problems + /// This will cause a warning that cannot be fixed if /// the consumer of the range only accepts a specific range type, instead of /// the generic `RangeBounds` trait /// ([#3307](https://github.com/rust-lang/rust-clippy/issues/3307)). /// - /// **Example:** + /// ### Example /// ```rust,ignore /// for x..=(y-1) { .. } /// ``` @@ -100,16 +106,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for range expressions `x..y` where both `x` and `y` + /// ### What it does + /// Checks for range expressions `x..y` where both `x` and `y` /// are constant and `x` is greater or equal to `y`. /// - /// **Why is this bad?** Empty ranges yield no values so iterating them is a no-op. + /// ### Why is this bad? + /// Empty ranges yield no values so iterating them is a no-op. /// Moreover, trying to use a reversed range to index a slice will panic at run-time. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust,no_run /// fn main() { /// (10..=0).for_each(|x| println!("{}", x)); @@ -133,16 +138,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for expressions like `x >= 3 && x < 8` that could + /// ### What it does + /// Checks for expressions like `x >= 3 && x < 8` that could /// be more readably expressed as `(3..8).contains(x)`. /// - /// **Why is this bad?** `contains` expresses the intent better and has less + /// ### Why is this bad? + /// `contains` expresses the intent better and has less /// failure modes (such as fencepost errors or using `||` instead of `&&`). /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// // given /// let x = 6; diff --git a/clippy_lints/src/redundant_clone.rs b/clippy_lints/src/redundant_clone.rs index 56ef95a88c880..530b3396abef6 100644 --- a/clippy_lints/src/redundant_clone.rs +++ b/clippy_lints/src/redundant_clone.rs @@ -32,17 +32,18 @@ macro_rules! unwrap_or_continue { } declare_clippy_lint! { - /// **What it does:** Checks for a redundant `clone()` (and its relatives) which clones an owned + /// ### What it does + /// Checks for a redundant `clone()` (and its relatives) which clones an owned /// value that is going to be dropped without further use. /// - /// **Why is this bad?** It is not always possible for the compiler to eliminate useless + /// ### Why is this bad? + /// It is not always possible for the compiler to eliminate useless /// allocations and deallocations generated by redundant `clone()`s. /// - /// **Known problems:** - /// + /// ### Known problems /// False-negatives: analysis performed by this lint is conservative and limited. /// - /// **Example:** + /// ### Example /// ```rust /// # use std::path::Path; /// # #[derive(Clone)] diff --git a/clippy_lints/src/redundant_closure_call.rs b/clippy_lints/src/redundant_closure_call.rs index 8f56a21ac5b3d..a79b2fe76e2d5 100644 --- a/clippy_lints/src/redundant_closure_call.rs +++ b/clippy_lints/src/redundant_closure_call.rs @@ -14,15 +14,15 @@ use rustc_middle::lint::in_external_macro; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Detects closures called in the same expression where they + /// ### What it does + /// Detects closures called in the same expression where they /// are defined. /// - /// **Why is this bad?** It is unnecessarily adding to the expression's + /// ### Why is this bad? + /// It is unnecessarily adding to the expression's /// complexity. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// // Bad /// let a = (|| 42)() diff --git a/clippy_lints/src/redundant_else.rs b/clippy_lints/src/redundant_else.rs index 061526c6f09fa..68b256d29442a 100644 --- a/clippy_lints/src/redundant_else.rs +++ b/clippy_lints/src/redundant_else.rs @@ -6,14 +6,16 @@ use rustc_middle::lint::in_external_macro; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for `else` blocks that can be removed without changing semantics. + /// ### What it does + /// Checks for `else` blocks that can be removed without changing semantics. /// - /// **Why is this bad?** The `else` block adds unnecessary indentation and verbosity. + /// ### Why is this bad? + /// The `else` block adds unnecessary indentation and verbosity. /// - /// **Known problems:** Some may prefer to keep the `else` block for clarity. - /// - /// **Example:** + /// ### Known problems + /// Some may prefer to keep the `else` block for clarity. /// + /// ### Example /// ```rust /// fn my_func(count: u32) { /// if count == 0 { diff --git a/clippy_lints/src/redundant_field_names.rs b/clippy_lints/src/redundant_field_names.rs index d5ee8d3468deb..47df4917510ff 100644 --- a/clippy_lints/src/redundant_field_names.rs +++ b/clippy_lints/src/redundant_field_names.rs @@ -8,15 +8,15 @@ use rustc_semver::RustcVersion; use rustc_session::{declare_tool_lint, impl_lint_pass}; declare_clippy_lint! { - /// **What it does:** Checks for fields in struct literals where shorthands + /// ### What it does + /// Checks for fields in struct literals where shorthands /// could be used. /// - /// **Why is this bad?** If the field and variable names are the same, + /// ### Why is this bad? + /// If the field and variable names are the same, /// the field name is redundant. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let bar: u8 = 123; /// diff --git a/clippy_lints/src/redundant_pub_crate.rs b/clippy_lints/src/redundant_pub_crate.rs index 05f9e01acb44b..59a55b9dffad4 100644 --- a/clippy_lints/src/redundant_pub_crate.rs +++ b/clippy_lints/src/redundant_pub_crate.rs @@ -5,16 +5,15 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_tool_lint, impl_lint_pass}; declare_clippy_lint! { - /// **What it does:** Checks for items declared `pub(crate)` that are not crate visible because they + /// ### What it does + /// Checks for items declared `pub(crate)` that are not crate visible because they /// are inside a private module. /// - /// **Why is this bad?** Writing `pub(crate)` is misleading when it's redundant due to the parent + /// ### Why is this bad? + /// Writing `pub(crate)` is misleading when it's redundant due to the parent /// module's visibility. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// mod internal { /// pub(crate) fn internal_fn() { } diff --git a/clippy_lints/src/redundant_slicing.rs b/clippy_lints/src/redundant_slicing.rs index 9c6cd7b4fa625..290348c4509ec 100644 --- a/clippy_lints/src/redundant_slicing.rs +++ b/clippy_lints/src/redundant_slicing.rs @@ -10,17 +10,19 @@ use rustc_middle::ty::TyS; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for redundant slicing expressions which use the full range, and + /// ### What it does + /// Checks for redundant slicing expressions which use the full range, and /// do not change the type. /// - /// **Why is this bad?** It unnecessarily adds complexity to the expression. + /// ### Why is this bad? + /// It unnecessarily adds complexity to the expression. /// - /// **Known problems:** If the type being sliced has an implementation of `Index<RangeFull>` + /// ### Known problems + /// If the type being sliced has an implementation of `Index<RangeFull>` /// that actually changes anything then it can't be removed. However, this would be surprising /// to people reading the code and should have a note with it. /// - /// **Example:** - /// + /// ### Example /// ```ignore /// fn get_slice(x: &[u32]) -> &[u32] { /// &x[..] diff --git a/clippy_lints/src/redundant_static_lifetimes.rs b/clippy_lints/src/redundant_static_lifetimes.rs index 48107d9c037db..d5a1a61da6bf4 100644 --- a/clippy_lints/src/redundant_static_lifetimes.rs +++ b/clippy_lints/src/redundant_static_lifetimes.rs @@ -8,14 +8,14 @@ use rustc_semver::RustcVersion; use rustc_session::{declare_tool_lint, impl_lint_pass}; declare_clippy_lint! { - /// **What it does:** Checks for constants and statics with an explicit `'static` lifetime. + /// ### What it does + /// Checks for constants and statics with an explicit `'static` lifetime. /// - /// **Why is this bad?** Adding `'static` to every reference can create very + /// ### Why is this bad? + /// Adding `'static` to every reference can create very /// complicated types. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// const FOO: &'static [(&'static str, &'static str, fn(&Bar) -> bool)] = /// &[...] diff --git a/clippy_lints/src/ref_option_ref.rs b/clippy_lints/src/ref_option_ref.rs index 0cf4e0ce7fe22..65ab6cac44219 100644 --- a/clippy_lints/src/ref_option_ref.rs +++ b/clippy_lints/src/ref_option_ref.rs @@ -9,16 +9,18 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::symbol::sym; declare_clippy_lint! { - /// **What it does:** Checks for usage of `&Option<&T>`. + /// ### What it does + /// Checks for usage of `&Option<&T>`. /// - /// **Why is this bad?** Since `&` is Copy, it's useless to have a + /// ### Why is this bad? + /// Since `&` is Copy, it's useless to have a /// reference on `Option<&T>`. /// - /// **Known problems:** It may be irrelevant to use this lint on + /// ### Known problems + /// It may be irrelevant to use this lint on /// public API code as it will make a breaking change to apply it. /// - /// **Example:** - /// + /// ### Example /// ```rust,ignore /// let x: &Option<&u32> = &Some(&0u32); /// ``` diff --git a/clippy_lints/src/reference.rs b/clippy_lints/src/reference.rs index d6336389b0af1..e0930d69ab9fe 100644 --- a/clippy_lints/src/reference.rs +++ b/clippy_lints/src/reference.rs @@ -10,15 +10,18 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::BytePos; declare_clippy_lint! { - /// **What it does:** Checks for usage of `*&` and `*&mut` in expressions. + /// ### What it does + /// Checks for usage of `*&` and `*&mut` in expressions. /// - /// **Why is this bad?** Immediately dereferencing a reference is no-op and + /// ### Why is this bad? + /// Immediately dereferencing a reference is no-op and /// makes the code less clear. /// - /// **Known problems:** Multiple dereference/addrof pairs are not handled so + /// ### Known problems + /// Multiple dereference/addrof pairs are not handled so /// the suggested fix for `x = **&&y` is `x = *&y`, which is still incorrect. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// // Bad /// let a = f(*&mut b); @@ -101,13 +104,15 @@ impl EarlyLintPass for DerefAddrOf { } declare_clippy_lint! { - /// **What it does:** Checks for references in expressions that use + /// ### What it does + /// Checks for references in expressions that use /// auto dereference. /// - /// **Why is this bad?** The reference is a no-op and is automatically + /// ### Why is this bad? + /// The reference is a no-op and is automatically /// dereferenced by the compiler and makes the code less clear. /// - /// **Example:** + /// ### Example /// ```rust /// struct Point(u32, u32); /// let point = Point(30, 20); diff --git a/clippy_lints/src/regex.rs b/clippy_lints/src/regex.rs index 751511674542d..eab097337306b 100644 --- a/clippy_lints/src/regex.rs +++ b/clippy_lints/src/regex.rs @@ -11,15 +11,15 @@ use rustc_span::source_map::{BytePos, Span}; use std::convert::TryFrom; declare_clippy_lint! { - /// **What it does:** Checks [regex](https://crates.io/crates/regex) creation + /// ### What it does + /// Checks [regex](https://crates.io/crates/regex) creation /// (with `Regex::new`, `RegexBuilder::new`, or `RegexSet::new`) for correct /// regex syntax. /// - /// **Why is this bad?** This will lead to a runtime panic. + /// ### Why is this bad? + /// This will lead to a runtime panic. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// Regex::new("|") /// ``` @@ -29,18 +29,21 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for trivial [regex](https://crates.io/crates/regex) + /// ### What it does + /// Checks for trivial [regex](https://crates.io/crates/regex) /// creation (with `Regex::new`, `RegexBuilder::new`, or `RegexSet::new`). /// - /// **Why is this bad?** Matching the regex can likely be replaced by `==` or + /// ### Why is this bad? + /// Matching the regex can likely be replaced by `==` or /// `str::starts_with`, `str::ends_with` or `std::contains` or other `str` /// methods. /// - /// **Known problems:** If the same regex is going to be applied to multiple + /// ### Known problems + /// If the same regex is going to be applied to multiple /// inputs, the precomputations done by `Regex` construction can give /// significantly better performance than any of the `str`-based methods. /// - /// **Example:** + /// ### Example /// ```ignore /// Regex::new("^foobar") /// ``` diff --git a/clippy_lints/src/repeat_once.rs b/clippy_lints/src/repeat_once.rs index 17cb96bc4ebd1..54b9c8b3275c6 100644 --- a/clippy_lints/src/repeat_once.rs +++ b/clippy_lints/src/repeat_once.rs @@ -11,7 +11,8 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for usage of `.repeat(1)` and suggest the following method for each types. + /// ### What it does + /// Checks for usage of `.repeat(1)` and suggest the following method for each types. /// - `.to_string()` for `str` /// - `.clone()` for `String` /// - `.to_vec()` for `slice` @@ -19,13 +20,11 @@ declare_clippy_lint! { /// The lint will evaluate constant expressions and values as arguments of `.repeat(..)` and emit a message if /// they are equivalent to `1`. (Related discussion in [rust-clippy#7306](https://github.com/rust-lang/rust-clippy/issues/7306)) /// - /// **Why is this bad?** For example, `String.repeat(1)` is equivalent to `.clone()`. If cloning + /// ### Why is this bad? + /// For example, `String.repeat(1)` is equivalent to `.clone()`. If cloning /// the string is the intention behind this, `clone()` should be used. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// fn main() { /// let x = String::from("hello world").repeat(1); diff --git a/clippy_lints/src/returns.rs b/clippy_lints/src/returns.rs index 251d527c26522..db4b1002ce129 100644 --- a/clippy_lints/src/returns.rs +++ b/clippy_lints/src/returns.rs @@ -15,15 +15,15 @@ use rustc_span::source_map::Span; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for `let`-bindings, which are subsequently + /// ### What it does + /// Checks for `let`-bindings, which are subsequently /// returned. /// - /// **Why is this bad?** It is just extraneous code. Remove it to make your code + /// ### Why is this bad? + /// It is just extraneous code. Remove it to make your code /// more rusty. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// fn foo() -> String { /// let x = String::new(); @@ -42,14 +42,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for return statements at the end of a block. + /// ### What it does + /// Checks for return statements at the end of a block. /// - /// **Why is this bad?** Removing the `return` and semicolon will make the code + /// ### Why is this bad? + /// Removing the `return` and semicolon will make the code /// more rusty. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// fn foo(x: usize) -> usize { /// return x; diff --git a/clippy_lints/src/self_assignment.rs b/clippy_lints/src/self_assignment.rs index e7925c4fbdeff..fbd65fef7d11b 100644 --- a/clippy_lints/src/self_assignment.rs +++ b/clippy_lints/src/self_assignment.rs @@ -6,16 +6,18 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for explicit self-assignments. + /// ### What it does + /// Checks for explicit self-assignments. /// - /// **Why is this bad?** Self-assignments are redundant and unlikely to be + /// ### Why is this bad? + /// Self-assignments are redundant and unlikely to be /// intentional. /// - /// **Known problems:** If expression contains any deref coercions or + /// ### Known problems + /// If expression contains any deref coercions or /// indexing operations they are assumed not to have any side effects. /// - /// **Example:** - /// + /// ### Example /// ```rust /// struct Event { /// id: usize, diff --git a/clippy_lints/src/self_named_constructor.rs b/clippy_lints/src/self_named_constructor.rs index da991e1d90c8e..2123a14cc1b82 100644 --- a/clippy_lints/src/self_named_constructor.rs +++ b/clippy_lints/src/self_named_constructor.rs @@ -6,14 +6,13 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Warns when constructors have the same name as their types. + /// ### What it does + /// Warns when constructors have the same name as their types. /// - /// **Why is this bad?** Repeating the name of the type is redundant. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// Repeating the name of the type is redundant. /// + /// ### Example /// ```rust,ignore /// struct Foo {} /// diff --git a/clippy_lints/src/semicolon_if_nothing_returned.rs b/clippy_lints/src/semicolon_if_nothing_returned.rs index da3e30af35ca4..6966230156cfa 100644 --- a/clippy_lints/src/semicolon_if_nothing_returned.rs +++ b/clippy_lints/src/semicolon_if_nothing_returned.rs @@ -9,16 +9,15 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Looks for blocks of expressions and fires if the last expression returns + /// ### What it does + /// Looks for blocks of expressions and fires if the last expression returns /// `()` but is not followed by a semicolon. /// - /// **Why is this bad?** The semicolon might be optional but when extending the block with new + /// ### Why is this bad? + /// The semicolon might be optional but when extending the block with new /// code, it doesn't require a change in previous last line. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// fn main() { /// println!("Hello world") diff --git a/clippy_lints/src/serde_api.rs b/clippy_lints/src/serde_api.rs index 169f7d26285cd..2cd0f85999cf5 100644 --- a/clippy_lints/src/serde_api.rs +++ b/clippy_lints/src/serde_api.rs @@ -5,14 +5,15 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for mis-uses of the serde API. + /// ### What it does + /// Checks for mis-uses of the serde API. /// - /// **Why is this bad?** Serde is very finnicky about how its API should be + /// ### Why is this bad? + /// Serde is very finnicky about how its API should be /// used, but the type system can't be used to enforce it (yet?). /// - /// **Known problems:** None. - /// - /// **Example:** Implementing `Visitor::visit_string` but not + /// ### Example + /// Implementing `Visitor::visit_string` but not /// `Visitor::visit_str`. pub SERDE_API_MISUSE, correctness, diff --git a/clippy_lints/src/shadow.rs b/clippy_lints/src/shadow.rs index ac3f7ebd14bd8..b28a37cabd40c 100644 --- a/clippy_lints/src/shadow.rs +++ b/clippy_lints/src/shadow.rs @@ -14,17 +14,20 @@ use rustc_span::source_map::Span; use rustc_span::symbol::Symbol; declare_clippy_lint! { - /// **What it does:** Checks for bindings that shadow other bindings already in + /// ### What it does + /// Checks for bindings that shadow other bindings already in /// scope, while just changing reference level or mutability. /// - /// **Why is this bad?** Not much, in fact it's a very common pattern in Rust + /// ### Why is this bad? + /// Not much, in fact it's a very common pattern in Rust /// code. Still, some may opt to avoid it in their code base, they can set this /// lint to `Warn`. /// - /// **Known problems:** This lint, as the other shadowing related lints, + /// ### Known problems + /// This lint, as the other shadowing related lints, /// currently only catches very simple patterns. /// - /// **Example:** + /// ### Example /// ```rust /// # let x = 1; /// // Bad @@ -39,18 +42,21 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for bindings that shadow other bindings already in + /// ### What it does + /// Checks for bindings that shadow other bindings already in /// scope, while reusing the original value. /// - /// **Why is this bad?** Not too much, in fact it's a common pattern in Rust + /// ### Why is this bad? + /// Not too much, in fact it's a common pattern in Rust /// code. Still, some argue that name shadowing like this hurts readability, /// because a value may be bound to different things depending on position in /// the code. /// - /// **Known problems:** This lint, as the other shadowing related lints, + /// ### Known problems + /// This lint, as the other shadowing related lints, /// currently only catches very simple patterns. /// - /// **Example:** + /// ### Example /// ```rust /// let x = 2; /// let x = x + 1; @@ -66,21 +72,24 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for bindings that shadow other bindings already in + /// ### What it does + /// Checks for bindings that shadow other bindings already in /// scope, either without a initialization or with one that does not even use /// the original value. /// - /// **Why is this bad?** Name shadowing can hurt readability, especially in + /// ### Why is this bad? + /// Name shadowing can hurt readability, especially in /// large code bases, because it is easy to lose track of the active binding at /// any place in the code. This can be alleviated by either giving more specific /// names to bindings or introducing more scopes to contain the bindings. /// - /// **Known problems:** This lint, as the other shadowing related lints, + /// ### Known problems + /// This lint, as the other shadowing related lints, /// currently only catches very simple patterns. Note that /// `allow`/`warn`/`deny`/`forbid` attributes only work on the function level /// for this lint. /// - /// **Example:** + /// ### Example /// ```rust /// # let y = 1; /// # let z = 2; diff --git a/clippy_lints/src/single_component_path_imports.rs b/clippy_lints/src/single_component_path_imports.rs index 1eaad438237ec..f6487b8c46bd4 100644 --- a/clippy_lints/src/single_component_path_imports.rs +++ b/clippy_lints/src/single_component_path_imports.rs @@ -7,15 +7,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::{edition::Edition, symbol::kw, Span, Symbol}; declare_clippy_lint! { - /// **What it does:** Checking for imports with single component use path. + /// ### What it does + /// Checking for imports with single component use path. /// - /// **Why is this bad?** Import with single component use path such as `use cratename;` + /// ### Why is this bad? + /// Import with single component use path such as `use cratename;` /// is not necessary, and thus should be removed. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust,ignore /// use regex; /// diff --git a/clippy_lints/src/size_of_in_element_count.rs b/clippy_lints/src/size_of_in_element_count.rs index b1965cfd601b1..3e4e4a8d0c08b 100644 --- a/clippy_lints/src/size_of_in_element_count.rs +++ b/clippy_lints/src/size_of_in_element_count.rs @@ -11,16 +11,16 @@ use rustc_middle::ty::{self, Ty, TyS, TypeAndMut}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Detects expressions where + /// ### What it does + /// Detects expressions where /// `size_of::<T>` or `size_of_val::<T>` is used as a /// count of elements of type `T` /// - /// **Why is this bad?** These functions expect a count + /// ### Why is this bad? + /// These functions expect a count /// of `T` and not a number of bytes /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,no_run /// # use std::ptr::copy_nonoverlapping; /// # use std::mem::size_of; diff --git a/clippy_lints/src/slow_vector_initialization.rs b/clippy_lints/src/slow_vector_initialization.rs index e5c58d70b603e..3d039e1306560 100644 --- a/clippy_lints/src/slow_vector_initialization.rs +++ b/clippy_lints/src/slow_vector_initialization.rs @@ -13,14 +13,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::symbol::sym; declare_clippy_lint! { - /// **What it does:** Checks slow zero-filled vector initialization + /// ### What it does + /// Checks slow zero-filled vector initialization /// - /// **Why is this bad?** These structures are non-idiomatic and less efficient than simply using + /// ### Why is this bad? + /// These structures are non-idiomatic and less efficient than simply using /// `vec![0; len]`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # use core::iter::repeat; /// # let len = 4; diff --git a/clippy_lints/src/stable_sort_primitive.rs b/clippy_lints/src/stable_sort_primitive.rs index 65790375c7379..4ea1293d504d3 100644 --- a/clippy_lints/src/stable_sort_primitive.rs +++ b/clippy_lints/src/stable_sort_primitive.rs @@ -7,22 +7,18 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// When sorting primitive values (integers, bools, chars, as well /// as arrays, slices, and tuples of such items), it is better to /// use an unstable sort than a stable sort. /// - /// **Why is this bad?** + /// ### Why is this bad? /// Using a stable sort consumes more memory and cpu cycles. Because /// values which compare equal are identical, preserving their /// relative order (the guarantee that a stable sort provides) means /// nothing, while the extra costs still apply. /// - /// **Known problems:** - /// None - /// - /// **Example:** - /// + /// ### Example /// ```rust /// let mut vec = vec![2, 1, 3]; /// vec.sort(); diff --git a/clippy_lints/src/strings.rs b/clippy_lints/src/strings.rs index 958e462125ef1..1a78a4968e5a3 100644 --- a/clippy_lints/src/strings.rs +++ b/clippy_lints/src/strings.rs @@ -14,16 +14,15 @@ use rustc_span::source_map::Spanned; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for string appends of the form `x = x + y` (without + /// ### What it does + /// Checks for string appends of the form `x = x + y` (without /// `let`!). /// - /// **Why is this bad?** It's not really bad, but some people think that the + /// ### Why is this bad? + /// It's not really bad, but some people think that the /// `.push_str(_)` method is more readable. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// let mut x = "Hello".to_owned(); /// x = x + ", World"; @@ -38,11 +37,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for all instances of `x + _` where `x` is of type + /// ### What it does + /// Checks for all instances of `x + _` where `x` is of type /// `String`, but only if [`string_add_assign`](#string_add_assign) does *not* /// match. /// - /// **Why is this bad?** It's not bad in and of itself. However, this particular + /// ### Why is this bad? + /// It's not bad in and of itself. However, this particular /// `Add` implementation is asymmetric (the other operand need not be `String`, /// but `x` does), while addition as mathematically defined is symmetric, also /// the `String::push_str(_)` function is a perfectly good replacement. @@ -52,10 +53,7 @@ declare_clippy_lint! { /// in other languages is actually fine, which is why we decided to make this /// particular lint `allow` by default. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// let x = "Hello".to_owned(); /// x + ", World"; @@ -66,13 +64,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for the `as_bytes` method called on string literals + /// ### What it does + /// Checks for the `as_bytes` method called on string literals /// that contain only ASCII characters. /// - /// **Why is this bad?** Byte string literals (e.g., `b"foo"`) can be used + /// ### Why is this bad? + /// Byte string literals (e.g., `b"foo"`) can be used /// instead. They are shorter but less discoverable than `as_bytes()`. /// - /// **Known Problems:** + /// ### Known problems /// `"str".as_bytes()` and the suggested replacement of `b"str"` are not /// equivalent because they have different types. The former is `&[u8]` /// while the latter is `&[u8; 3]`. That means in general they will have a @@ -94,7 +94,7 @@ declare_clippy_lint! { /// `b"str"` but `&b"str"[..]`, which is a great deal of punctuation and not /// more readable than a function call. /// - /// **Example:** + /// ### Example /// ```rust /// // Bad /// let bs = "a byte string".as_bytes(); @@ -177,13 +177,13 @@ fn is_add(cx: &LateContext<'_>, src: &Expr<'_>, target: &Expr<'_>) -> bool { } declare_clippy_lint! { - /// **What it does:** Check if the string is transformed to byte array and casted back to string. + /// ### What it does + /// Check if the string is transformed to byte array and casted back to string. /// - /// **Why is this bad?** It's unnecessary, the string can be used directly. + /// ### Why is this bad? + /// It's unnecessary, the string can be used directly. /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```rust /// let _ = std::str::from_utf8(&"Hello World!".as_bytes()[6..11]).unwrap(); /// ``` @@ -317,16 +317,15 @@ impl<'tcx> LateLintPass<'tcx> for StringLitAsBytes { } declare_clippy_lint! { - /// **What it does:** This lint checks for `.to_string()` method calls on values of type `&str`. + /// ### What it does + /// This lint checks for `.to_string()` method calls on values of type `&str`. /// - /// **Why is this bad?** The `to_string` method is also used on other types to convert them to a string. + /// ### Why is this bad? + /// The `to_string` method is also used on other types to convert them to a string. /// When called on a `&str` it turns the `&str` into the owned variant `String`, which can be better /// expressed with `.to_owned()`. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// // example code where clippy issues a warning /// let _ = "str".to_string(); @@ -366,14 +365,14 @@ impl LateLintPass<'_> for StrToString { } declare_clippy_lint! { - /// **What it does:** This lint checks for `.to_string()` method calls on values of type `String`. + /// ### What it does + /// This lint checks for `.to_string()` method calls on values of type `String`. /// - /// **Why is this bad?** The `to_string` method is also used on other types to convert them to a string. + /// ### Why is this bad? + /// The `to_string` method is also used on other types to convert them to a string. /// When called on a `String` it only clones the `String`, which can be better expressed with `.clone()`. - /// **Known problems:** None. - /// - /// **Example:** /// + /// ### Example /// ```rust /// // example code where clippy issues a warning /// let msg = String::from("Hello World"); diff --git a/clippy_lints/src/strlen_on_c_strings.rs b/clippy_lints/src/strlen_on_c_strings.rs index 2ccf3a3796d51..516fa3d95b428 100644 --- a/clippy_lints/src/strlen_on_c_strings.rs +++ b/clippy_lints/src/strlen_on_c_strings.rs @@ -11,16 +11,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::symbol::{sym, Symbol}; declare_clippy_lint! { - /// **What it does:** Checks for usage of `libc::strlen` on a `CString` or `CStr` value, + /// ### What it does + /// Checks for usage of `libc::strlen` on a `CString` or `CStr` value, /// and suggest calling `as_bytes().len()` or `to_bytes().len()` respectively instead. /// - /// **Why is this bad?** This avoids calling an unsafe `libc` function. + /// ### Why is this bad? + /// This avoids calling an unsafe `libc` function. /// Currently, it also avoids calculating the length. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust, ignore /// use std::ffi::CString; /// let cstring = CString::new("foo").expect("CString::new failed"); diff --git a/clippy_lints/src/suspicious_operation_groupings.rs b/clippy_lints/src/suspicious_operation_groupings.rs index bb707f78fccd8..a8e962d1af3fa 100644 --- a/clippy_lints/src/suspicious_operation_groupings.rs +++ b/clippy_lints/src/suspicious_operation_groupings.rs @@ -13,20 +13,21 @@ use rustc_span::symbol::Ident; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// Checks for unlikely usages of binary operators that are almost /// certainly typos and/or copy/paste errors, given the other usages /// of binary operators nearby. - /// **Why is this bad?** + /// + /// ### Why is this bad? /// They are probably bugs and if they aren't then they look like bugs /// and you should add a comment explaining why you are doing such an /// odd set of operations. - /// **Known problems:** + /// + /// ### Known problems /// There may be some false positives if you are trying to do something /// unusual that happens to look like a typo. /// - /// **Example:** - /// + /// ### Example /// ```rust /// struct Vec3 { /// x: f64, diff --git a/clippy_lints/src/suspicious_trait_impl.rs b/clippy_lints/src/suspicious_trait_impl.rs index f2bffd553210b..682fad00a13ee 100644 --- a/clippy_lints/src/suspicious_trait_impl.rs +++ b/clippy_lints/src/suspicious_trait_impl.rs @@ -8,14 +8,14 @@ use rustc_middle::hir::map::Map; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Lints for suspicious operations in impls of arithmetic operators, e.g. + /// ### What it does + /// Lints for suspicious operations in impls of arithmetic operators, e.g. /// subtracting elements in an Add impl. /// - /// **Why this is bad?** This is probably a typo or copy-and-paste error and not intended. + /// ### Why is this bad? + /// This is probably a typo or copy-and-paste error and not intended. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```ignore /// impl Add for Foo { /// type Output = Foo; @@ -31,14 +31,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Lints for suspicious operations in impls of OpAssign, e.g. + /// ### What it does + /// Lints for suspicious operations in impls of OpAssign, e.g. /// subtracting elements in an AddAssign impl. /// - /// **Why this is bad?** This is probably a typo or copy-and-paste error and not intended. - /// - /// **Known problems:** None. + /// ### Why is this bad? + /// This is probably a typo or copy-and-paste error and not intended. /// - /// **Example:** + /// ### Example /// ```ignore /// impl AddAssign for Foo { /// fn add_assign(&mut self, other: Foo) { diff --git a/clippy_lints/src/swap.rs b/clippy_lints/src/swap.rs index 19967e2c97014..4fa8e77a67b78 100644 --- a/clippy_lints/src/swap.rs +++ b/clippy_lints/src/swap.rs @@ -12,14 +12,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for manual swapping. + /// ### What it does + /// Checks for manual swapping. /// - /// **Why is this bad?** The `std::mem::swap` function exposes the intent better + /// ### Why is this bad? + /// The `std::mem::swap` function exposes the intent better /// without deinitializing or copying either variable. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let mut a = 42; /// let mut b = 1337; @@ -40,13 +40,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `foo = bar; bar = foo` sequences. - /// - /// **Why is this bad?** This looks like a failed attempt to swap. + /// ### What it does + /// Checks for `foo = bar; bar = foo` sequences. /// - /// **Known problems:** None. + /// ### Why is this bad? + /// This looks like a failed attempt to swap. /// - /// **Example:** + /// ### Example /// ```rust /// # let mut a = 1; /// # let mut b = 2; diff --git a/clippy_lints/src/tabs_in_doc_comments.rs b/clippy_lints/src/tabs_in_doc_comments.rs index e2c144709f5b7..6a73b94d87e48 100644 --- a/clippy_lints/src/tabs_in_doc_comments.rs +++ b/clippy_lints/src/tabs_in_doc_comments.rs @@ -7,16 +7,16 @@ use rustc_span::source_map::{BytePos, Span}; use std::convert::TryFrom; declare_clippy_lint! { - /// **What it does:** Checks doc comments for usage of tab characters. + /// ### What it does + /// Checks doc comments for usage of tab characters. /// - /// **Why is this bad?** The rust style-guide promotes spaces instead of tabs for indentation. + /// ### Why is this bad? + /// The rust style-guide promotes spaces instead of tabs for indentation. /// To keep a consistent view on the source, also doc comments should not have tabs. /// Also, explaining ascii-diagrams containing tabs can get displayed incorrectly when the /// display settings of the author and reader differ. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// /// /// /// Struct to hold two strings: diff --git a/clippy_lints/src/temporary_assignment.rs b/clippy_lints/src/temporary_assignment.rs index 8ef25dc816c65..a9da690339ccf 100644 --- a/clippy_lints/src/temporary_assignment.rs +++ b/clippy_lints/src/temporary_assignment.rs @@ -5,15 +5,15 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for construction of a structure or tuple just to + /// ### What it does + /// Checks for construction of a structure or tuple just to /// assign a value in it. /// - /// **Why is this bad?** Readability. If the structure is only created to be + /// ### Why is this bad? + /// Readability. If the structure is only created to be /// updated, why not write the structure you want in the first place? /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// (0, 0).0 = 1 /// ``` diff --git a/clippy_lints/src/to_digit_is_some.rs b/clippy_lints/src/to_digit_is_some.rs index c66a596c78461..1c14a9199950c 100644 --- a/clippy_lints/src/to_digit_is_some.rs +++ b/clippy_lints/src/to_digit_is_some.rs @@ -9,12 +9,14 @@ use rustc_middle::ty; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for `.to_digit(..).is_some()` on `char`s. + /// ### What it does + /// Checks for `.to_digit(..).is_some()` on `char`s. /// - /// **Why is this bad?** This is a convoluted way of checking if a `char` is a digit. It's + /// ### Why is this bad? + /// This is a convoluted way of checking if a `char` is a digit. It's /// more straight forward to use the dedicated `is_digit` method. /// - /// **Example:** + /// ### Example /// ```rust /// # let c = 'c'; /// # let radix = 10; diff --git a/clippy_lints/src/to_string_in_display.rs b/clippy_lints/src/to_string_in_display.rs index 4fb297ac6c699..b036ed9a3d2e7 100644 --- a/clippy_lints/src/to_string_in_display.rs +++ b/clippy_lints/src/to_string_in_display.rs @@ -7,15 +7,15 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::symbol::sym; declare_clippy_lint! { - /// **What it does:** Checks for uses of `to_string()` in `Display` traits. + /// ### What it does + /// Checks for uses of `to_string()` in `Display` traits. /// - /// **Why is this bad?** Usually `to_string` is implemented indirectly + /// ### Why is this bad? + /// Usually `to_string` is implemented indirectly /// via `Display`. Hence using it while implementing `Display` would /// lead to infinite recursion. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// /// ```rust /// use std::fmt; diff --git a/clippy_lints/src/trait_bounds.rs b/clippy_lints/src/trait_bounds.rs index 74a94db180006..79367c4230c2a 100644 --- a/clippy_lints/src/trait_bounds.rs +++ b/clippy_lints/src/trait_bounds.rs @@ -11,14 +11,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** This lint warns about unnecessary type repetitions in trait bounds + /// ### What it does + /// This lint warns about unnecessary type repetitions in trait bounds /// - /// **Why is this bad?** Repeating the type for every bound makes the code + /// ### Why is this bad? + /// Repeating the type for every bound makes the code /// less readable than combining the bounds /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// pub fn foo<T>(t: T) where T: Copy, T: Clone {} /// ``` @@ -34,15 +34,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for cases where generics are being used and multiple + /// ### What it does + /// Checks for cases where generics are being used and multiple /// syntax specifications for trait bounds are used simultaneously. /// - /// **Why is this bad?** Duplicate bounds makes the code + /// ### Why is this bad? + /// Duplicate bounds makes the code /// less readable than specifing them only once. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// fn func<T: Clone + Default>(arg: T) where T: Clone + Default {} /// ``` diff --git a/clippy_lints/src/transmute/mod.rs b/clippy_lints/src/transmute/mod.rs index 89fd5faa165f4..33ec9c331ce56 100644 --- a/clippy_lints/src/transmute/mod.rs +++ b/clippy_lints/src/transmute/mod.rs @@ -20,15 +20,18 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::symbol::sym; declare_clippy_lint! { - /// **What it does:** Checks for transmutes that can't ever be correct on any + /// ### What it does + /// Checks for transmutes that can't ever be correct on any /// architecture. /// - /// **Why is this bad?** It's basically guaranteed to be undefined behaviour. + /// ### Why is this bad? + /// It's basically guaranteed to be undefined behaviour. /// - /// **Known problems:** When accessing C, users might want to store pointer + /// ### Known problems + /// When accessing C, users might want to store pointer /// sized objects in `extradata` arguments to save an allocation. /// - /// **Example:** + /// ### Example /// ```ignore /// let ptr: *const T = core::intrinsics::transmute('x') /// ``` @@ -39,15 +42,15 @@ declare_clippy_lint! { // FIXME: Move this to `complexity` again, after #5343 is fixed declare_clippy_lint! { - /// **What it does:** Checks for transmutes to the original type of the object + /// ### What it does + /// Checks for transmutes to the original type of the object /// and transmutes that could be a cast. /// - /// **Why is this bad?** Readability. The code tricks people into thinking that + /// ### Why is this bad? + /// Readability. The code tricks people into thinking that /// something complex is going on. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// core::intrinsics::transmute(t); // where the result type is the same as `t`'s /// ``` @@ -58,14 +61,14 @@ declare_clippy_lint! { // FIXME: Merge this lint with USELESS_TRANSMUTE once that is out of the nursery. declare_clippy_lint! { - /// **What it does:**Checks for transmutes that could be a pointer cast. + /// ### What it does + ///Checks for transmutes that could be a pointer cast. /// - /// **Why is this bad?** Readability. The code tricks people into thinking that + /// ### Why is this bad? + /// Readability. The code tricks people into thinking that /// something complex is going on. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// /// ```rust /// # let p: *const [i32] = &[]; @@ -82,14 +85,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for transmutes between a type `T` and `*T`. + /// ### What it does + /// Checks for transmutes between a type `T` and `*T`. /// - /// **Why is this bad?** It's easy to mistakenly transmute between a type and a + /// ### Why is this bad? + /// It's easy to mistakenly transmute between a type and a /// pointer to that type. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// core::intrinsics::transmute(t) // where the result type is the same as /// // `*t` or `&t`'s @@ -100,17 +103,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for transmutes from a pointer to a reference. + /// ### What it does + /// Checks for transmutes from a pointer to a reference. /// - /// **Why is this bad?** This can always be rewritten with `&` and `*`. + /// ### Why is this bad? + /// This can always be rewritten with `&` and `*`. /// - /// **Known problems:** + /// ### Known problems /// - `mem::transmute` in statics and constants is stable from Rust 1.46.0, /// while dereferencing raw pointer is not stable yet. /// If you need to do this in those places, /// you would have to use `transmute` instead. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// unsafe { /// let _: &T = std::mem::transmute(p); // where p: *const T @@ -125,11 +130,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for transmutes from an integer to a `char`. + /// ### What it does + /// Checks for transmutes from an integer to a `char`. /// - /// **Why is this bad?** Not every integer is a Unicode scalar value. + /// ### Why is this bad? + /// Not every integer is a Unicode scalar value. /// - /// **Known problems:** + /// ### Known problems /// - [`from_u32`] which this lint suggests using is slower than `transmute` /// as it needs to validate the input. /// If you are certain that the input is always a valid Unicode scalar value, @@ -140,7 +147,7 @@ declare_clippy_lint! { /// [`from_u32`]: https://doc.rust-lang.org/std/char/fn.from_u32.html /// [`from_u32_unchecked`]: https://doc.rust-lang.org/std/char/fn.from_u32_unchecked.html /// - /// **Example:** + /// ### Example /// ```rust /// let x = 1_u32; /// unsafe { @@ -156,11 +163,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for transmutes from a `&[u8]` to a `&str`. + /// ### What it does + /// Checks for transmutes from a `&[u8]` to a `&str`. /// - /// **Why is this bad?** Not every byte slice is a valid UTF-8 string. + /// ### Why is this bad? + /// Not every byte slice is a valid UTF-8 string. /// - /// **Known problems:** + /// ### Known problems /// - [`from_utf8`] which this lint suggests using is slower than `transmute` /// as it needs to validate the input. /// If you are certain that the input is always a valid UTF-8, @@ -171,7 +180,7 @@ declare_clippy_lint! { /// [`from_utf8`]: https://doc.rust-lang.org/std/str/fn.from_utf8.html /// [`from_utf8_unchecked`]: https://doc.rust-lang.org/std/str/fn.from_utf8_unchecked.html /// - /// **Example:** + /// ### Example /// ```rust /// let b: &[u8] = &[1_u8, 2_u8]; /// unsafe { @@ -187,13 +196,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for transmutes from an integer to a `bool`. - /// - /// **Why is this bad?** This might result in an invalid in-memory representation of a `bool`. + /// ### What it does + /// Checks for transmutes from an integer to a `bool`. /// - /// **Known problems:** None. + /// ### Why is this bad? + /// This might result in an invalid in-memory representation of a `bool`. /// - /// **Example:** + /// ### Example /// ```rust /// let x = 1_u8; /// unsafe { @@ -209,14 +218,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for transmutes from an integer to a float. + /// ### What it does + /// Checks for transmutes from an integer to a float. /// - /// **Why is this bad?** Transmutes are dangerous and error-prone, whereas `from_bits` is intuitive + /// ### Why is this bad? + /// Transmutes are dangerous and error-prone, whereas `from_bits` is intuitive /// and safe. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// unsafe { /// let _: f32 = std::mem::transmute(1_u32); // where x: u32 @@ -231,14 +240,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for transmutes from a float to an integer. + /// ### What it does + /// Checks for transmutes from a float to an integer. /// - /// **Why is this bad?** Transmutes are dangerous and error-prone, whereas `to_bits` is intuitive + /// ### Why is this bad? + /// Transmutes are dangerous and error-prone, whereas `to_bits` is intuitive /// and safe. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// unsafe { /// let _: u32 = std::mem::transmute(1f32); @@ -253,15 +262,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for transmutes from a pointer to a pointer, or + /// ### What it does + /// Checks for transmutes from a pointer to a pointer, or /// from a reference to a reference. /// - /// **Why is this bad?** Transmutes are dangerous, and these can instead be + /// ### Why is this bad? + /// Transmutes are dangerous, and these can instead be /// written as casts. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let ptr = &1u32 as *const u32; /// unsafe { @@ -280,15 +289,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for transmutes between collections whose + /// ### What it does + /// Checks for transmutes between collections whose /// types have different ABI, size or alignment. /// - /// **Why is this bad?** This is undefined behavior. + /// ### Why is this bad? + /// This is undefined behavior. /// - /// **Known problems:** Currently, we cannot know whether a type is a + /// ### Known problems + /// Currently, we cannot know whether a type is a /// collection, so we just lint the ones that come with `std`. /// - /// **Example:** + /// ### Example /// ```rust /// // different size, therefore likely out-of-bounds memory access /// // You absolutely do not want this in your code! diff --git a/clippy_lints/src/transmuting_null.rs b/clippy_lints/src/transmuting_null.rs index 0c39d4d8cf466..a67fa7922059c 100644 --- a/clippy_lints/src/transmuting_null.rs +++ b/clippy_lints/src/transmuting_null.rs @@ -10,15 +10,18 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::symbol::sym; declare_clippy_lint! { - /// **What it does:** Checks for transmute calls which would receive a null pointer. + /// ### What it does + /// Checks for transmute calls which would receive a null pointer. /// - /// **Why is this bad?** Transmuting a null pointer is undefined behavior. + /// ### Why is this bad? + /// Transmuting a null pointer is undefined behavior. /// - /// **Known problems:** Not all cases can be detected at the moment of this writing. + /// ### Known problems + /// Not all cases can be detected at the moment of this writing. /// For example, variables which hold a null pointer and are then fed to a `transmute` /// call, aren't detectable yet. /// - /// **Example:** + /// ### Example /// ```rust /// let null_ref: &u64 = unsafe { std::mem::transmute(0 as *const u64) }; /// ``` diff --git a/clippy_lints/src/try_err.rs b/clippy_lints/src/try_err.rs index f2ba2b2ecf639..1196271d5dd13 100644 --- a/clippy_lints/src/try_err.rs +++ b/clippy_lints/src/try_err.rs @@ -13,16 +13,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for usages of `Err(x)?`. + /// ### What it does + /// Checks for usages of `Err(x)?`. /// - /// **Why is this bad?** The `?` operator is designed to allow calls that + /// ### Why is this bad? + /// The `?` operator is designed to allow calls that /// can fail to be easily chained. For example, `foo()?.bar()` or /// `foo(bar()?)`. Because `Err(x)?` can't be used that way (it will /// always return), it is more clear to write `return Err(x)`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// fn foo(fail: bool) -> Result<i32, String> { /// if fail { diff --git a/clippy_lints/src/types/mod.rs b/clippy_lints/src/types/mod.rs index 7d629b5455b62..ad7409fe3a9b7 100644 --- a/clippy_lints/src/types/mod.rs +++ b/clippy_lints/src/types/mod.rs @@ -20,16 +20,16 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::source_map::Span; declare_clippy_lint! { - /// **What it does:** Checks for use of `Box<Vec<_>>` anywhere in the code. + /// ### What it does + /// Checks for use of `Box<Vec<_>>` anywhere in the code. /// Check the [Box documentation](https://doc.rust-lang.org/std/boxed/index.html) for more information. /// - /// **Why is this bad?** `Vec` already keeps its contents in a separate area on + /// ### Why is this bad? + /// `Vec` already keeps its contents in a separate area on /// the heap. So if you `Box` it, you just add another level of indirection /// without any benefit whatsoever. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// struct X { /// values: Box<Vec<Foo>>, @@ -49,16 +49,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for use of `Vec<Box<T>>` where T: Sized anywhere in the code. + /// ### What it does + /// Checks for use of `Vec<Box<T>>` where T: Sized anywhere in the code. /// Check the [Box documentation](https://doc.rust-lang.org/std/boxed/index.html) for more information. /// - /// **Why is this bad?** `Vec` already keeps its contents in a separate area on + /// ### Why is this bad? + /// `Vec` already keeps its contents in a separate area on /// the heap. So if you `Box` its contents, you just add another level of indirection. /// - /// **Known problems:** Vec<Box<T: Sized>> makes sense if T is a large type (see [#3530](https://github.com/rust-lang/rust-clippy/issues/3530), + /// ### Known problems + /// Vec<Box<T: Sized>> makes sense if T is a large type (see [#3530](https://github.com/rust-lang/rust-clippy/issues/3530), /// 1st comment). /// - /// **Example:** + /// ### Example /// ```rust /// struct X { /// values: Vec<Box<i32>>, @@ -78,19 +81,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for use of `Option<Option<_>>` in function signatures and type + /// ### What it does + /// Checks for use of `Option<Option<_>>` in function signatures and type /// definitions /// - /// **Why is this bad?** `Option<_>` represents an optional value. `Option<Option<_>>` + /// ### Why is this bad? + /// `Option<_>` represents an optional value. `Option<Option<_>>` /// represents an optional optional value which is logically the same thing as an optional /// value but has an unneeded extra level of wrapping. /// /// If you have a case where `Some(Some(_))`, `Some(None)` and `None` are distinct cases, /// consider a custom `enum` instead, with clear names for each case. /// - /// **Known problems:** None. - /// - /// **Example** + /// ### Example /// ```rust /// fn get_data() -> Option<Option<u32>> { /// None @@ -116,10 +119,12 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for usage of any `LinkedList`, suggesting to use a + /// ### What it does + /// Checks for usage of any `LinkedList`, suggesting to use a /// `Vec` or a `VecDeque` (formerly called `RingBuf`). /// - /// **Why is this bad?** Gankro says: + /// ### Why is this bad? + /// Gankro says: /// /// > The TL;DR of `LinkedList` is that it's built on a massive amount of /// pointers and indirection. @@ -138,10 +143,11 @@ declare_clippy_lint! { /// can still be better /// > because of how expensive it is to seek to the middle of a `LinkedList`. /// - /// **Known problems:** False positives – the instances where using a + /// ### Known problems + /// False positives – the instances where using a /// `LinkedList` makes sense are few and far between, but they can still happen. /// - /// **Example:** + /// ### Example /// ```rust /// # use std::collections::LinkedList; /// let x: LinkedList<usize> = LinkedList::new(); @@ -152,15 +158,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for use of `&Box<T>` anywhere in the code. + /// ### What it does + /// Checks for use of `&Box<T>` anywhere in the code. /// Check the [Box documentation](https://doc.rust-lang.org/std/boxed/index.html) for more information. /// - /// **Why is this bad?** Any `&Box<T>` can also be a `&T`, which is more + /// ### Why is this bad? + /// Any `&Box<T>` can also be a `&T`, which is more /// general. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// fn foo(bar: &Box<T>) { ... } /// ``` @@ -176,14 +182,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for use of redundant allocations anywhere in the code. + /// ### What it does + /// Checks for use of redundant allocations anywhere in the code. /// - /// **Why is this bad?** Expressions such as `Rc<&T>`, `Rc<Rc<T>>`, `Rc<Arc<T>>`, `Rc<Box<T>>`, Arc<&T>`, `Arc<Rc<T>>`, + /// ### Why is this bad? + /// Expressions such as `Rc<&T>`, `Rc<Rc<T>>`, `Rc<Arc<T>>`, `Rc<Box<T>>`, Arc<&T>`, `Arc<Rc<T>>`, /// `Arc<Arc<T>>`, `Arc<Box<T>>`, `Box<&T>`, `Box<Rc<T>>`, `Box<Arc<T>>`, `Box<Box<T>>`, add an unnecessary level of indirection. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # use std::rc::Rc; /// fn foo(bar: Rc<&usize>) {} @@ -200,9 +206,11 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `Rc<T>` and `Arc<T>` when `T` is a mutable buffer type such as `String` or `Vec`. + /// ### What it does + /// Checks for `Rc<T>` and `Arc<T>` when `T` is a mutable buffer type such as `String` or `Vec`. /// - /// **Why is this bad?** Expressions such as `Rc<String>` usually have no advantage over `Rc<str>`, since + /// ### Why is this bad? + /// Expressions such as `Rc<String>` usually have no advantage over `Rc<str>`, since /// it is larger and involves an extra level of indirection, and doesn't implement `Borrow<str>`. /// /// While mutating a buffer type would still be possible with `Rc::get_mut()`, it only @@ -211,10 +219,11 @@ declare_clippy_lint! { /// type with an interior mutable container (such as `RefCell` or `Mutex`) would normally /// be used. /// - /// **Known problems:** This pattern can be desirable to avoid the overhead of a `RefCell` or `Mutex` for + /// ### Known problems + /// This pattern can be desirable to avoid the overhead of a `RefCell` or `Mutex` for /// cases where mutation only happens before there are any additional references. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// # use std::rc::Rc; /// fn foo(interned: Rc<String>) { ... } @@ -231,15 +240,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for types used in structs, parameters and `let` + /// ### What it does + /// Checks for types used in structs, parameters and `let` /// declarations above a certain complexity threshold. /// - /// **Why is this bad?** Too complex types make the code less readable. Consider + /// ### Why is this bad? + /// Too complex types make the code less readable. Consider /// using a `type` definition to simplify them. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # use std::rc::Rc; /// struct Foo { @@ -252,16 +261,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for `Rc<Mutex<T>>`. + /// ### What it does + /// Checks for `Rc<Mutex<T>>`. /// - /// **Why is this bad?** `Rc` is used in single thread and `Mutex` is used in multi thread. + /// ### Why is this bad? + /// `Rc` is used in single thread and `Mutex` is used in multi thread. /// Consider using `Rc<RefCell<T>>` in single thread or `Arc<Mutex<T>>` in multi thread. /// - /// **Known problems:** Sometimes combining generic types can lead to the requirement that a + /// ### Known problems + /// Sometimes combining generic types can lead to the requirement that a /// type use Rc in conjunction with Mutex. We must consider those cases false positives, but /// alas they are quite hard to rule out. Luckily they are also rare. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// use std::rc::Rc; /// use std::sync::Mutex; diff --git a/clippy_lints/src/undropped_manually_drops.rs b/clippy_lints/src/undropped_manually_drops.rs index f4f5e1233e351..47571e608c780 100644 --- a/clippy_lints/src/undropped_manually_drops.rs +++ b/clippy_lints/src/undropped_manually_drops.rs @@ -6,15 +6,17 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Prevents the safe `std::mem::drop` function from being called on `std::mem::ManuallyDrop`. + /// ### What it does + /// Prevents the safe `std::mem::drop` function from being called on `std::mem::ManuallyDrop`. /// - /// **Why is this bad?** The safe `drop` function does not drop the inner value of a `ManuallyDrop`. + /// ### Why is this bad? + /// The safe `drop` function does not drop the inner value of a `ManuallyDrop`. /// - /// **Known problems:** Does not catch cases if the user binds `std::mem::drop` + /// ### Known problems + /// Does not catch cases if the user binds `std::mem::drop` /// to a different name and calls it that way. /// - /// **Example:** - /// + /// ### Example /// ```rust /// struct S; /// drop(std::mem::ManuallyDrop::new(S)); diff --git a/clippy_lints/src/unicode.rs b/clippy_lints/src/unicode.rs index 2f0a61898ba75..f337dec8f2b96 100644 --- a/clippy_lints/src/unicode.rs +++ b/clippy_lints/src/unicode.rs @@ -10,14 +10,15 @@ use rustc_span::source_map::Span; use unicode_normalization::UnicodeNormalization; declare_clippy_lint! { - /// **What it does:** Checks for invisible Unicode characters in the code. + /// ### What it does + /// Checks for invisible Unicode characters in the code. /// - /// **Why is this bad?** Having an invisible character in the code makes for all + /// ### Why is this bad? + /// Having an invisible character in the code makes for all /// sorts of April fools, but otherwise is very much frowned upon. /// - /// **Known problems:** None. - /// - /// **Example:** You don't see it, but there may be a zero-width space or soft hyphen + /// ### Example + /// You don't see it, but there may be a zero-width space or soft hyphen /// somewhere in this text. pub INVISIBLE_CHARACTERS, correctness, @@ -25,17 +26,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for non-ASCII characters in string literals. + /// ### What it does + /// Checks for non-ASCII characters in string literals. /// - /// **Why is this bad?** Yeah, we know, the 90's called and wanted their charset + /// ### Why is this bad? + /// Yeah, we know, the 90's called and wanted their charset /// back. Even so, there still are editors and other programs out there that /// don't work well with Unicode. So if the code is meant to be used /// internationally, on multiple operating systems, or has other portability /// requirements, activating this lint could be useful. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x = String::from("€"); /// ``` @@ -49,16 +50,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for string literals that contain Unicode in a form + /// ### What it does + /// Checks for string literals that contain Unicode in a form /// that is not equal to its /// [NFC-recomposition](http://www.unicode.org/reports/tr15/#Norm_Forms). /// - /// **Why is this bad?** If such a string is compared to another, the results + /// ### Why is this bad? + /// If such a string is compared to another, the results /// may be surprising. /// - /// **Known problems** None. - /// - /// **Example:** You may not see it, but "à"" and "à"" aren't the same string. The + /// ### Example + /// You may not see it, but "à"" and "à"" aren't the same string. The /// former when escaped is actually `"a\u{300}"` while the latter is `"\u{e0}"`. pub UNICODE_NOT_NFC, pedantic, diff --git a/clippy_lints/src/unit_return_expecting_ord.rs b/clippy_lints/src/unit_return_expecting_ord.rs index 1c420a5042721..900d453176071 100644 --- a/clippy_lints/src/unit_return_expecting_ord.rs +++ b/clippy_lints/src/unit_return_expecting_ord.rs @@ -10,20 +10,22 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::{BytePos, Span}; declare_clippy_lint! { - /// **What it does:** Checks for functions that expect closures of type + /// ### What it does + /// Checks for functions that expect closures of type /// Fn(...) -> Ord where the implemented closure returns the unit type. /// The lint also suggests to remove the semi-colon at the end of the statement if present. /// - /// **Why is this bad?** Likely, returning the unit type is unintentional, and + /// ### Why is this bad? + /// Likely, returning the unit type is unintentional, and /// could simply be caused by an extra semi-colon. Since () implements Ord /// it doesn't cause a compilation error. /// This is the same reasoning behind the unit_cmp lint. /// - /// **Known problems:** If returning unit is intentional, then there is no + /// ### Known problems + /// If returning unit is intentional, then there is no /// way of specifying this without triggering needless_return lint /// - /// **Example:** - /// + /// ### Example /// ```rust /// let mut twins = vec!((1, 1), (2, 2)); /// twins.sort_by_key(|x| { x.1; }); diff --git a/clippy_lints/src/unit_types/mod.rs b/clippy_lints/src/unit_types/mod.rs index 64420a0393349..66b1abbe50b9d 100644 --- a/clippy_lints/src/unit_types/mod.rs +++ b/clippy_lints/src/unit_types/mod.rs @@ -8,14 +8,14 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for binding a unit value. + /// ### What it does + /// Checks for binding a unit value. /// - /// **Why is this bad?** A unit value cannot usefully be used anywhere. So + /// ### Why is this bad? + /// A unit value cannot usefully be used anywhere. So /// binding one is kind of pointless. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// let x = { /// 1; @@ -27,16 +27,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for comparisons to unit. This includes all binary + /// ### What it does + /// Checks for comparisons to unit. This includes all binary /// comparisons (like `==` and `<`) and asserts. /// - /// **Why is this bad?** Unit is always equal to itself, and thus is just a + /// ### Why is this bad? + /// Unit is always equal to itself, and thus is just a /// clumsily written constant. Mostly this happens when someone accidentally /// adds semicolons at the end of the operands. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # fn foo() {}; /// # fn bar() {}; @@ -74,14 +74,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for passing a unit value as an argument to a function without using a + /// ### What it does + /// Checks for passing a unit value as an argument to a function without using a /// unit literal (`()`). /// - /// **Why is this bad?** This is likely the result of an accidental semicolon. - /// - /// **Known problems:** None. + /// ### Why is this bad? + /// This is likely the result of an accidental semicolon. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// foo({ /// let a = bar(); diff --git a/clippy_lints/src/unnamed_address.rs b/clippy_lints/src/unnamed_address.rs index 9cca05b1f1a65..1eafdee03521c 100644 --- a/clippy_lints/src/unnamed_address.rs +++ b/clippy_lints/src/unnamed_address.rs @@ -7,16 +7,15 @@ use rustc_middle::ty; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for comparisons with an address of a function item. + /// ### What it does + /// Checks for comparisons with an address of a function item. /// - /// **Why is this bad?** Function item address is not guaranteed to be unique and could vary + /// ### Why is this bad? + /// Function item address is not guaranteed to be unique and could vary /// between different code generation units. Furthermore different function items could have /// the same address after being merged together. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// type F = fn(); /// fn a() {} @@ -31,17 +30,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for comparisons with an address of a trait vtable. + /// ### What it does + /// Checks for comparisons with an address of a trait vtable. /// - /// **Why is this bad?** Comparing trait objects pointers compares an vtable addresses which + /// ### Why is this bad? + /// Comparing trait objects pointers compares an vtable addresses which /// are not guaranteed to be unique and could vary between different code generation units. /// Furthermore vtables for different types could have the same address after being merged /// together. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust,ignore /// let a: Rc<dyn Trait> = ... /// let b: Rc<dyn Trait> = ... diff --git a/clippy_lints/src/unnecessary_self_imports.rs b/clippy_lints/src/unnecessary_self_imports.rs index 48c54d79cf113..4cfd2df551f1b 100644 --- a/clippy_lints/src/unnecessary_self_imports.rs +++ b/clippy_lints/src/unnecessary_self_imports.rs @@ -7,16 +7,18 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::symbol::kw; declare_clippy_lint! { - /// **What it does:** Checks for imports ending in `::{self}`. + /// ### What it does + /// Checks for imports ending in `::{self}`. /// - /// **Why is this bad?** In most cases, this can be written much more cleanly by omitting `::{self}`. + /// ### Why is this bad? + /// In most cases, this can be written much more cleanly by omitting `::{self}`. /// - /// **Known problems:** Removing `::{self}` will cause any non-module items at the same path to also be imported. + /// ### Known problems + /// Removing `::{self}` will cause any non-module items at the same path to also be imported. /// This might cause a naming conflict (https://github.com/rust-lang/rustfmt/issues/3568). This lint makes no attempt /// to detect this scenario and that is why it is a restriction lint. /// - /// **Example:** - /// + /// ### Example /// ```rust /// use std::io::{self}; /// ``` diff --git a/clippy_lints/src/unnecessary_sort_by.rs b/clippy_lints/src/unnecessary_sort_by.rs index 347d858b64026..6fc5707a4eeff 100644 --- a/clippy_lints/src/unnecessary_sort_by.rs +++ b/clippy_lints/src/unnecessary_sort_by.rs @@ -12,21 +12,20 @@ use rustc_span::symbol::Ident; use std::iter; declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// Detects uses of `Vec::sort_by` passing in a closure /// which compares the two arguments, either directly or indirectly. /// - /// **Why is this bad?** + /// ### Why is this bad? /// It is more clear to use `Vec::sort_by_key` (or `Vec::sort` if /// possible) than to use `Vec::sort_by` and a more complicated /// closure. /// - /// **Known problems:** + /// ### Known problems /// If the suggested `Vec::sort_by_key` uses Reverse and it isn't already /// imported by a use statement, then it will need to be added manually. /// - /// **Example:** - /// + /// ### Example /// ```rust /// # struct A; /// # impl A { fn foo(&self) {} } diff --git a/clippy_lints/src/unnecessary_wraps.rs b/clippy_lints/src/unnecessary_wraps.rs index a85ffa6aa9505..7a62b21937ff0 100644 --- a/clippy_lints/src/unnecessary_wraps.rs +++ b/clippy_lints/src/unnecessary_wraps.rs @@ -13,15 +13,17 @@ use rustc_span::symbol::sym; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** Checks for private functions that only return `Ok` or `Some`. + /// ### What it does + /// Checks for private functions that only return `Ok` or `Some`. /// - /// **Why is this bad?** It is not meaningful to wrap values when no `None` or `Err` is returned. + /// ### Why is this bad? + /// It is not meaningful to wrap values when no `None` or `Err` is returned. /// - /// **Known problems:** There can be false positives if the function signature is designed to + /// ### Known problems + /// There can be false positives if the function signature is designed to /// fit some external requirement. /// - /// **Example:** - /// + /// ### Example /// ```rust /// fn get_cool_number(a: bool, b: bool) -> Option<i32> { /// if a && b { diff --git a/clippy_lints/src/unnested_or_patterns.rs b/clippy_lints/src/unnested_or_patterns.rs index 07a4e29404979..9acfbc994b382 100644 --- a/clippy_lints/src/unnested_or_patterns.rs +++ b/clippy_lints/src/unnested_or_patterns.rs @@ -17,22 +17,17 @@ use std::cell::Cell; use std::mem; declare_clippy_lint! { - /// **What it does:** - /// + /// ### What it does /// Checks for unnested or-patterns, e.g., `Some(0) | Some(2)` and /// suggests replacing the pattern with a nested one, `Some(0 | 2)`. /// /// Another way to think of this is that it rewrites patterns in /// *disjunctive normal form (DNF)* into *conjunctive normal form (CNF)*. /// - /// **Why is this bad?** - /// + /// ### Why is this bad? /// In the example above, `Some` is repeated, which unncessarily complicates the pattern. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// fn main() { /// if let Some(0) | Some(2) = Some(0) {} diff --git a/clippy_lints/src/unsafe_removed_from_name.rs b/clippy_lints/src/unsafe_removed_from_name.rs index 16ad9d2dfd32c..3c694af2b9dee 100644 --- a/clippy_lints/src/unsafe_removed_from_name.rs +++ b/clippy_lints/src/unsafe_removed_from_name.rs @@ -6,15 +6,15 @@ use rustc_span::source_map::Span; use rustc_span::symbol::Ident; declare_clippy_lint! { - /// **What it does:** Checks for imports that remove "unsafe" from an item's + /// ### What it does + /// Checks for imports that remove "unsafe" from an item's /// name. /// - /// **Why is this bad?** Renaming makes it less clear which traits and + /// ### Why is this bad? + /// Renaming makes it less clear which traits and /// structures are unsafe. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// use std::cell::{UnsafeCell as TotallySafeCell}; /// diff --git a/clippy_lints/src/unused_async.rs b/clippy_lints/src/unused_async.rs index 18ee07d3a9587..3a6a07c522630 100644 --- a/clippy_lints/src/unused_async.rs +++ b/clippy_lints/src/unused_async.rs @@ -7,16 +7,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::Span; declare_clippy_lint! { - /// **What it does:** Checks for functions that are declared `async` but have no `.await`s inside of them. + /// ### What it does + /// Checks for functions that are declared `async` but have no `.await`s inside of them. /// - /// **Why is this bad?** Async functions with no async code create overhead, both mentally and computationally. + /// ### Why is this bad? + /// Async functions with no async code create overhead, both mentally and computationally. /// Callers of async methods either need to be calling from an async function themselves or run it on an executor, both of which /// causes runtime overhead and hassle for the caller. /// - /// **Known problems:** None - /// - /// **Example:** - /// + /// ### Example /// ```rust /// // Bad /// async fn get_random_number() -> i64 { diff --git a/clippy_lints/src/unused_io_amount.rs b/clippy_lints/src/unused_io_amount.rs index ee082d30d936b..82bc4a6d15343 100644 --- a/clippy_lints/src/unused_io_amount.rs +++ b/clippy_lints/src/unused_io_amount.rs @@ -5,9 +5,11 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for unused written/read amount. + /// ### What it does + /// Checks for unused written/read amount. /// - /// **Why is this bad?** `io::Write::write(_vectored)` and + /// ### Why is this bad? + /// `io::Write::write(_vectored)` and /// `io::Read::read(_vectored)` are not guaranteed to /// process the entire buffer. They return how many bytes were processed, which /// might be smaller @@ -15,9 +17,10 @@ declare_clippy_lint! { /// partial-write/read, use /// `write_all`/`read_exact` instead. /// - /// **Known problems:** Detects only common patterns. + /// ### Known problems + /// Detects only common patterns. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// use std::io; /// fn foo<W: io::Write>(w: &mut W) -> io::Result<()> { diff --git a/clippy_lints/src/unused_self.rs b/clippy_lints/src/unused_self.rs index 15343cf90f231..658ac81f6eac8 100644 --- a/clippy_lints/src/unused_self.rs +++ b/clippy_lints/src/unused_self.rs @@ -6,14 +6,14 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks methods that contain a `self` argument but don't use it + /// ### What it does + /// Checks methods that contain a `self` argument but don't use it /// - /// **Why is this bad?** It may be clearer to define the method as an associated function instead + /// ### Why is this bad? + /// It may be clearer to define the method as an associated function instead /// of an instance method if it doesn't require `self`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust,ignore /// struct A; /// impl A { diff --git a/clippy_lints/src/unused_unit.rs b/clippy_lints/src/unused_unit.rs index ab0cdf75ffe0a..9ed5e585f841d 100644 --- a/clippy_lints/src/unused_unit.rs +++ b/clippy_lints/src/unused_unit.rs @@ -10,15 +10,15 @@ use rustc_span::source_map::Span; use rustc_span::BytePos; declare_clippy_lint! { - /// **What it does:** Checks for unit (`()`) expressions that can be removed. + /// ### What it does + /// Checks for unit (`()`) expressions that can be removed. /// - /// **Why is this bad?** Such expressions add no value, but can make the code + /// ### Why is this bad? + /// Such expressions add no value, but can make the code /// less readable. Depending on formatting they can make a `break` or `return` /// statement look like a function call. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// fn return_unit() -> () { /// () diff --git a/clippy_lints/src/unwrap.rs b/clippy_lints/src/unwrap.rs index d4efee56efff5..c5b8acb9982d8 100644 --- a/clippy_lints/src/unwrap.rs +++ b/clippy_lints/src/unwrap.rs @@ -13,13 +13,13 @@ use rustc_span::source_map::Span; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for calls of `unwrap[_err]()` that cannot fail. + /// ### What it does + /// Checks for calls of `unwrap[_err]()` that cannot fail. /// - /// **Why is this bad?** Using `if let` or `match` is more idiomatic. + /// ### Why is this bad? + /// Using `if let` or `match` is more idiomatic. /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// ```rust /// # let option = Some(0); /// # fn do_something_with(_x: usize) {} @@ -43,14 +43,17 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for calls of `unwrap[_err]()` that will always fail. + /// ### What it does + /// Checks for calls of `unwrap[_err]()` that will always fail. /// - /// **Why is this bad?** If panicking is desired, an explicit `panic!()` should be used. + /// ### Why is this bad? + /// If panicking is desired, an explicit `panic!()` should be used. /// - /// **Known problems:** This lint only checks `if` conditions not assignments. + /// ### Known problems + /// This lint only checks `if` conditions not assignments. /// So something like `let x: Option<()> = None; x.unwrap();` will not be recognized. /// - /// **Example:** + /// ### Example /// ```rust /// # let option = Some(0); /// # fn do_something_with(_x: usize) {} diff --git a/clippy_lints/src/unwrap_in_result.rs b/clippy_lints/src/unwrap_in_result.rs index d17aa6d842411..6eadd1fc1c933 100644 --- a/clippy_lints/src/unwrap_in_result.rs +++ b/clippy_lints/src/unwrap_in_result.rs @@ -12,13 +12,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::{sym, Span}; declare_clippy_lint! { - /// **What it does:** Checks for functions of type Result that contain `expect()` or `unwrap()` + /// ### What it does + /// Checks for functions of type Result that contain `expect()` or `unwrap()` /// - /// **Why is this bad?** These functions promote recoverable errors to non-recoverable errors which may be undesirable in code bases which wish to avoid panics. + /// ### Why is this bad? + /// These functions promote recoverable errors to non-recoverable errors which may be undesirable in code bases which wish to avoid panics. /// - /// **Known problems:** This can cause false positives in functions that handle both recoverable and non recoverable errors. + /// ### Known problems + /// This can cause false positives in functions that handle both recoverable and non recoverable errors. /// - /// **Example:** + /// ### Example /// Before: /// ```rust /// fn divisible_by_3(i_str: String) -> Result<(), String> { diff --git a/clippy_lints/src/upper_case_acronyms.rs b/clippy_lints/src/upper_case_acronyms.rs index 0b58c6c0917ca..7fa0e23ee73ea 100644 --- a/clippy_lints/src/upper_case_acronyms.rs +++ b/clippy_lints/src/upper_case_acronyms.rs @@ -8,9 +8,11 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::symbol::Ident; declare_clippy_lint! { - /// **What it does:** Checks for fully capitalized names and optionally names containing a capitalized acronym. + /// ### What it does + /// Checks for fully capitalized names and optionally names containing a capitalized acronym. /// - /// **Why is this bad?** In CamelCase, acronyms count as one word. + /// ### Why is this bad? + /// In CamelCase, acronyms count as one word. /// See [naming conventions](https://rust-lang.github.io/api-guidelines/naming.html#casing-conforms-to-rfc-430-c-case) /// for more. /// @@ -18,12 +20,12 @@ declare_clippy_lint! { /// You can use the `upper-case-acronyms-aggressive: true` config option to enable linting /// on all camel case names /// - /// **Known problems:** When two acronyms are contiguous, the lint can't tell where + /// ### Known problems + /// When two acronyms are contiguous, the lint can't tell where /// the first acronym ends and the second starts, so it suggests to lowercase all of /// the letters in the second acronym. /// - /// **Example:** - /// + /// ### Example /// ```rust /// struct HTTPResponse; /// ``` diff --git a/clippy_lints/src/use_self.rs b/clippy_lints/src/use_self.rs index 71117e967e319..fbd552186df86 100644 --- a/clippy_lints/src/use_self.rs +++ b/clippy_lints/src/use_self.rs @@ -20,19 +20,20 @@ use rustc_span::Span; use rustc_typeck::hir_ty_to_ty; declare_clippy_lint! { - /// **What it does:** Checks for unnecessary repetition of structure name when a + /// ### What it does + /// Checks for unnecessary repetition of structure name when a /// replacement with `Self` is applicable. /// - /// **Why is this bad?** Unnecessary repetition. Mixed use of `Self` and struct + /// ### Why is this bad? + /// Unnecessary repetition. Mixed use of `Self` and struct /// name /// feels inconsistent. /// - /// **Known problems:** + /// ### Known problems /// - Unaddressed false negative in fn bodies of trait implementations /// - False positive with assotiated types in traits (#4140) /// - /// **Example:** - /// + /// ### Example /// ```rust /// struct Foo {} /// impl Foo { diff --git a/clippy_lints/src/useless_conversion.rs b/clippy_lints/src/useless_conversion.rs index 25a959d3e416c..2861b43291901 100644 --- a/clippy_lints/src/useless_conversion.rs +++ b/clippy_lints/src/useless_conversion.rs @@ -12,15 +12,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass}; use rustc_span::sym; declare_clippy_lint! { - /// **What it does:** Checks for `Into`, `TryInto`, `From`, `TryFrom`, or `IntoIter` calls + /// ### What it does + /// Checks for `Into`, `TryInto`, `From`, `TryFrom`, or `IntoIter` calls /// which uselessly convert to the same type. /// - /// **Why is this bad?** Redundant code. - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? + /// Redundant code. /// + /// ### Example /// ```rust /// // Bad /// // format!() returns a `String` diff --git a/clippy_lints/src/utils/author.rs b/clippy_lints/src/utils/author.rs index c1e7fd7fe9578..61fd375a9892c 100644 --- a/clippy_lints/src/utils/author.rs +++ b/clippy_lints/src/utils/author.rs @@ -13,9 +13,10 @@ use rustc_middle::hir::map::Map; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Generates clippy code that detects the offending pattern + /// ### What it does + /// Generates clippy code that detects the offending pattern /// - /// **Example:** + /// ### Example /// ```rust,ignore /// // ./tests/ui/my_lint.rs /// fn foo() { diff --git a/clippy_lints/src/utils/inspector.rs b/clippy_lints/src/utils/inspector.rs index 4665eeeff7b21..f7ddee12dcf64 100644 --- a/clippy_lints/src/utils/inspector.rs +++ b/clippy_lints/src/utils/inspector.rs @@ -8,10 +8,11 @@ use rustc_session::Session; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Dumps every ast/hir node which has the `#[clippy::dump]` + /// ### What it does + /// Dumps every ast/hir node which has the `#[clippy::dump]` /// attribute /// - /// **Example:** + /// ### Example /// ```rust,ignore /// #[clippy::dump] /// extern crate foo; diff --git a/clippy_lints/src/utils/internal_lints.rs b/clippy_lints/src/utils/internal_lints.rs index 668807f499f3f..d660008e7d184 100644 --- a/clippy_lints/src/utils/internal_lints.rs +++ b/clippy_lints/src/utils/internal_lints.rs @@ -36,29 +36,33 @@ use std::borrow::{Borrow, Cow}; pub mod metadata_collector; declare_clippy_lint! { - /// **What it does:** Checks for various things we like to keep tidy in clippy. + /// ### What it does + /// Checks for various things we like to keep tidy in clippy. /// - /// **Why is this bad?** We like to pretend we're an example of tidy code. + /// ### Why is this bad? + /// We like to pretend we're an example of tidy code. /// - /// **Known problems:** None. - /// - /// **Example:** Wrong ordering of the util::paths constants. + /// ### Example + /// Wrong ordering of the util::paths constants. pub CLIPPY_LINTS_INTERNAL, internal, "various things that will negatively affect your clippy experience" } declare_clippy_lint! { - /// **What it does:** Ensures every lint is associated to a `LintPass`. + /// ### What it does + /// Ensures every lint is associated to a `LintPass`. /// - /// **Why is this bad?** The compiler only knows lints via a `LintPass`. Without + /// ### Why is this bad? + /// The compiler only knows lints via a `LintPass`. Without /// putting a lint to a `LintPass::get_lints()`'s return, the compiler will not /// know the name of the lint. /// - /// **Known problems:** Only checks for lints associated using the + /// ### Known problems + /// Only checks for lints associated using the /// `declare_lint_pass!`, `impl_lint_pass!`, and `lint_array!` macros. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// declare_lint! { pub LINT_1, ... } /// declare_lint! { pub LINT_2, ... } @@ -73,15 +77,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for calls to `cx.span_lint*` and suggests to use the `utils::*` + /// ### What it does + /// Checks for calls to `cx.span_lint*` and suggests to use the `utils::*` /// variant of the function. /// - /// **Why is this bad?** The `utils::*` variants also add a link to the Clippy documentation to the + /// ### Why is this bad? + /// The `utils::*` variants also add a link to the Clippy documentation to the /// warning/error messages. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// Bad: /// ```rust,ignore /// cx.span_lint(LINT_NAME, "message"); @@ -97,14 +101,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for calls to `cx.outer().expn_data()` and suggests to use + /// ### What it does + /// Checks for calls to `cx.outer().expn_data()` and suggests to use /// the `cx.outer_expn_data()` /// - /// **Why is this bad?** `cx.outer_expn_data()` is faster and more concise. - /// - /// **Known problems:** None. + /// ### Why is this bad? + /// `cx.outer_expn_data()` is faster and more concise. /// - /// **Example:** + /// ### Example /// Bad: /// ```rust,ignore /// expr.span.ctxt().outer().expn_data() @@ -120,14 +124,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Not an actual lint. This lint is only meant for testing our customized internal compiler + /// ### What it does + /// Not an actual lint. This lint is only meant for testing our customized internal compiler /// error message by calling `panic`. /// - /// **Why is this bad?** ICE in large quantities can damage your teeth + /// ### Why is this bad? + /// ICE in large quantities can damage your teeth /// - /// **Known problems:** None - /// - /// **Example:** + /// ### Example /// Bad: /// ```rust,ignore /// 🍦🍦🍦🍦🍦 @@ -138,14 +142,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for cases of an auto-generated lint without an updated description, + /// ### What it does + /// Checks for cases of an auto-generated lint without an updated description, /// i.e. `default lint description`. /// - /// **Why is this bad?** Indicates that the lint is not finished. - /// - /// **Known problems:** None + /// ### Why is this bad? + /// Indicates that the lint is not finished. /// - /// **Example:** + /// ### Example /// Bad: /// ```rust,ignore /// declare_lint! { pub COOL_LINT, nursery, "default lint description" } @@ -161,7 +165,8 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Lints `span_lint_and_then` function calls, where the + /// ### What it does + /// Lints `span_lint_and_then` function calls, where the /// closure argument has only one statement and that statement is a method /// call to `span_suggestion`, `span_help`, `span_note` (using the same /// span), `help` or `note`. @@ -170,12 +175,11 @@ declare_clippy_lint! { /// wrapper functions `span_lint_and_sugg`, span_lint_and_help`, or /// `span_lint_and_note`. /// - /// **Why is this bad?** Using the wrapper `span_lint_and_*` functions, is more + /// ### Why is this bad? + /// Using the wrapper `span_lint_and_*` functions, is more /// convenient, readable and less error prone. /// - /// **Known problems:** None - /// - /// *Example:** + /// ### Example /// Bad: /// ```rust,ignore /// span_lint_and_then(cx, TEST_LINT, expr.span, lint_msg, |diag| { @@ -222,14 +226,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for calls to `utils::match_type()` on a type diagnostic item + /// ### What it does + /// Checks for calls to `utils::match_type()` on a type diagnostic item /// and suggests to use `utils::is_type_diagnostic_item()` instead. /// - /// **Why is this bad?** `utils::is_type_diagnostic_item()` does not require hardcoded paths. - /// - /// **Known problems:** None. + /// ### Why is this bad? + /// `utils::is_type_diagnostic_item()` does not require hardcoded paths. /// - /// **Example:** + /// ### Example /// Bad: /// ```rust,ignore /// utils::match_type(cx, ty, &paths::VEC) @@ -245,30 +249,27 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// Checks the paths module for invalid paths. /// - /// **Why is this bad?** + /// ### Why is this bad? /// It indicates a bug in the code. /// - /// **Known problems:** None. - /// - /// **Example:** None. + /// ### Example + /// None. pub INVALID_PATHS, internal, "invalid path" } declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// Checks for interning symbols that have already been pre-interned and defined as constants. /// - /// **Why is this bad?** + /// ### Why is this bad? /// It's faster and easier to use the symbol constant. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// Bad: /// ```rust,ignore /// let _ = sym!(f32); @@ -284,13 +285,13 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for unnecessary conversion from Symbol to a string. - /// - /// **Why is this bad?** It's faster use symbols directly intead of strings. + /// ### What it does + /// Checks for unnecessary conversion from Symbol to a string. /// - /// **Known problems:** None. + /// ### Why is this bad? + /// It's faster use symbols directly intead of strings. /// - /// **Example:** + /// ### Example /// Bad: /// ```rust,ignore /// symbol.as_str() == "clippy"; diff --git a/clippy_lints/src/utils/internal_lints/metadata_collector.rs b/clippy_lints/src/utils/internal_lints/metadata_collector.rs index 3eccc89cdeb80..3244677b301b7 100644 --- a/clippy_lints/src/utils/internal_lints/metadata_collector.rs +++ b/clippy_lints/src/utils/internal_lints/metadata_collector.rs @@ -68,7 +68,7 @@ const CLIPPY_LINT_GROUP_PREFIX: &str = "clippy::"; macro_rules! CONFIGURATION_SECTION_TEMPLATE { () => { r#" -**Configuration** +### Configuration This lint has the following configuration variables: {configurations} @@ -116,18 +116,21 @@ const DEPRECATED_LINT_TYPE: [&str; 3] = ["clippy_lints", "deprecated_lints", "Cl const APPLICABILITY_NAME_INDEX: usize = 2; declare_clippy_lint! { - /// **What it does:** Collects metadata about clippy lints for the website. + /// ### What it does + /// Collects metadata about clippy lints for the website. /// /// This lint will be used to report problems of syntax parsing. You should hopefully never /// see this but never say never I guess ^^ /// - /// **Why is this bad?** This is not a bad thing but definitely a hacky way to do it. See + /// ### Why is this bad? + /// This is not a bad thing but definitely a hacky way to do it. See /// issue [#4310](https://github.com/rust-lang/rust-clippy/issues/4310) for a discussion /// about the implementation. /// - /// **Known problems:** Hopefully none. It would be pretty uncool to have a problem here :) + /// ### Known problems + /// Hopefully none. It would be pretty uncool to have a problem here :) /// - /// **Example output:** + /// ### Example output /// ```json,ignore /// { /// "id": "internal_metadata_collector", @@ -374,7 +377,8 @@ impl<'hir> LateLintPass<'hir> for MetadataCollector { /// Collecting lint declarations like: /// ```rust, ignore /// declare_clippy_lint! { - /// /// **What it does:** Something IDK. + /// /// ### What it does + /// /// Something IDK. /// pub SOME_LINT, /// internal, /// "Who am I?" diff --git a/clippy_lints/src/vec.rs b/clippy_lints/src/vec.rs index 1d5b7c98d3141..32fa46f042ce1 100644 --- a/clippy_lints/src/vec.rs +++ b/clippy_lints/src/vec.rs @@ -19,14 +19,14 @@ pub struct UselessVec { } declare_clippy_lint! { - /// **What it does:** Checks for usage of `&vec![..]` when using `&[..]` would + /// ### What it does + /// Checks for usage of `&vec![..]` when using `&[..]` would /// be possible. /// - /// **Why is this bad?** This is less efficient. + /// ### Why is this bad? + /// This is less efficient. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # fn foo(my_vec: &[u8]) {} /// diff --git a/clippy_lints/src/vec_init_then_push.rs b/clippy_lints/src/vec_init_then_push.rs index c7190e2f9798c..0413c02b230e5 100644 --- a/clippy_lints/src/vec_init_then_push.rs +++ b/clippy_lints/src/vec_init_then_push.rs @@ -13,15 +13,14 @@ use rustc_span::{symbol::sym, Span}; use std::convert::TryInto; declare_clippy_lint! { - /// **What it does:** Checks for calls to `push` immediately after creating a new `Vec`. + /// ### What it does + /// Checks for calls to `push` immediately after creating a new `Vec`. /// - /// **Why is this bad?** The `vec![]` macro is both more performant and easier to read than + /// ### Why is this bad? + /// The `vec![]` macro is both more performant and easier to read than /// multiple `push` calls. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust /// let mut v = Vec::new(); /// v.push(0); diff --git a/clippy_lints/src/vec_resize_to_zero.rs b/clippy_lints/src/vec_resize_to_zero.rs index 5540e87405ff9..5c0429db6b8df 100644 --- a/clippy_lints/src/vec_resize_to_zero.rs +++ b/clippy_lints/src/vec_resize_to_zero.rs @@ -10,13 +10,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint}; use rustc_span::source_map::Spanned; declare_clippy_lint! { - /// **What it does:** Finds occurrences of `Vec::resize(0, an_int)` + /// ### What it does + /// Finds occurrences of `Vec::resize(0, an_int)` /// - /// **Why is this bad?** This is probably an argument inversion mistake. + /// ### Why is this bad? + /// This is probably an argument inversion mistake. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// vec!(1, 2, 3, 4, 5).resize(0, 5) /// ``` diff --git a/clippy_lints/src/verbose_file_reads.rs b/clippy_lints/src/verbose_file_reads.rs index 3ab68df2b6d7c..e07c12f4f1615 100644 --- a/clippy_lints/src/verbose_file_reads.rs +++ b/clippy_lints/src/verbose_file_reads.rs @@ -7,15 +7,14 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for use of File::read_to_end and File::read_to_string. + /// ### What it does + /// Checks for use of File::read_to_end and File::read_to_string. /// - /// **Why is this bad?** `fs::{read, read_to_string}` provide the same functionality when `buf` is empty with fewer imports and no intermediate values. + /// ### Why is this bad? + /// `fs::{read, read_to_string}` provide the same functionality when `buf` is empty with fewer imports and no intermediate values. /// See also: [fs::read docs](https://doc.rust-lang.org/std/fs/fn.read.html), [fs::read_to_string docs](https://doc.rust-lang.org/std/fs/fn.read_to_string.html) /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```rust,no_run /// # use std::io::Read; /// # use std::fs::File; diff --git a/clippy_lints/src/wildcard_dependencies.rs b/clippy_lints/src/wildcard_dependencies.rs index 1ca1117a41ea5..fd3872bacbe24 100644 --- a/clippy_lints/src/wildcard_dependencies.rs +++ b/clippy_lints/src/wildcard_dependencies.rs @@ -7,16 +7,15 @@ use rustc_span::source_map::DUMMY_SP; use if_chain::if_chain; declare_clippy_lint! { - /// **What it does:** Checks for wildcard dependencies in the `Cargo.toml`. + /// ### What it does + /// Checks for wildcard dependencies in the `Cargo.toml`. /// - /// **Why is this bad?** [As the edition guide says](https://rust-lang-nursery.github.io/edition-guide/rust-2018/cargo-and-crates-io/crates-io-disallows-wildcard-dependencies.html), + /// ### Why is this bad? + /// [As the edition guide says](https://rust-lang-nursery.github.io/edition-guide/rust-2018/cargo-and-crates-io/crates-io-disallows-wildcard-dependencies.html), /// it is highly unlikely that you work with any possible version of your dependency, /// and wildcard dependencies would cause unnecessary breakage in the ecosystem. /// - /// **Known problems:** None. - /// - /// **Example:** - /// + /// ### Example /// ```toml /// [dependencies] /// regex = "*" diff --git a/clippy_lints/src/wildcard_imports.rs b/clippy_lints/src/wildcard_imports.rs index 520586b3a1f42..bafb9d3e3b16a 100644 --- a/clippy_lints/src/wildcard_imports.rs +++ b/clippy_lints/src/wildcard_imports.rs @@ -13,15 +13,18 @@ use rustc_span::symbol::kw; use rustc_span::{sym, BytePos}; declare_clippy_lint! { - /// **What it does:** Checks for `use Enum::*`. + /// ### What it does + /// Checks for `use Enum::*`. /// - /// **Why is this bad?** It is usually better style to use the prefixed name of + /// ### Why is this bad? + /// It is usually better style to use the prefixed name of /// an enumeration variant, rather than importing variants. /// - /// **Known problems:** Old-style enumerations that prefix the variants are + /// ### Known problems + /// Old-style enumerations that prefix the variants are /// still around. /// - /// **Example:** + /// ### Example /// ```rust,ignore /// // Bad /// use std::cmp::Ordering::*; @@ -37,9 +40,11 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for wildcard imports `use _::*`. + /// ### What it does + /// Checks for wildcard imports `use _::*`. /// - /// **Why is this bad?** wildcard imports can pollute the namespace. This is especially bad if + /// ### Why is this bad? + /// wildcard imports can pollute the namespace. This is especially bad if /// you try to import something through a wildcard, that already has been imported by name from /// a different source: /// @@ -52,8 +57,7 @@ declare_clippy_lint! { /// /// This can lead to confusing error messages at best and to unexpected behavior at worst. /// - /// **Exceptions:** - /// + /// ### Exceptions /// Wildcard imports are allowed from modules named `prelude`. Many crates (including the standard library) /// provide modules named "prelude" specifically designed for wildcard import. /// @@ -61,14 +65,14 @@ declare_clippy_lint! { /// /// These exceptions can be disabled using the `warn-on-all-wildcard-imports` configuration flag. /// - /// **Known problems:** If macros are imported through the wildcard, this macro is not included + /// ### Known problems + /// If macros are imported through the wildcard, this macro is not included /// by the suggestion and has to be added by hand. /// /// Applying the suggestion when explicit imports of the things imported with a glob import /// exist, may result in `unused_imports` warnings. /// - /// **Example:** - /// + /// ### Example /// ```rust,ignore /// // Bad /// use crate1::*; diff --git a/clippy_lints/src/write.rs b/clippy_lints/src/write.rs index 5229a7058659c..4553ac704a28f 100644 --- a/clippy_lints/src/write.rs +++ b/clippy_lints/src/write.rs @@ -16,14 +16,14 @@ use rustc_span::symbol::{kw, Symbol}; use rustc_span::{sym, BytePos, Span, DUMMY_SP}; declare_clippy_lint! { - /// **What it does:** This lint warns when you use `println!("")` to + /// ### What it does + /// This lint warns when you use `println!("")` to /// print a newline. /// - /// **Why is this bad?** You should use `println!()`, which is simpler. + /// ### Why is this bad? + /// You should use `println!()`, which is simpler. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// // Bad /// println!(""); @@ -37,15 +37,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** This lint warns when you use `print!()` with a format + /// ### What it does + /// This lint warns when you use `print!()` with a format /// string that ends in a newline. /// - /// **Why is this bad?** You should use `println!()` instead, which appends the + /// ### Why is this bad? + /// You should use `println!()` instead, which appends the /// newline. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # let name = "World"; /// print!("Hello {}!\n", name); @@ -61,15 +61,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for printing on *stdout*. The purpose of this lint + /// ### What it does + /// Checks for printing on *stdout*. The purpose of this lint /// is to catch debugging remnants. /// - /// **Why is this bad?** People often print on *stdout* while debugging an + /// ### Why is this bad? + /// People often print on *stdout* while debugging an /// application and might forget to remove those prints afterward. /// - /// **Known problems:** Only catches `print!` and `println!` calls. + /// ### Known problems + /// Only catches `print!` and `println!` calls. /// - /// **Example:** + /// ### Example /// ```rust /// println!("Hello world!"); /// ``` @@ -79,15 +82,18 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for printing on *stderr*. The purpose of this lint + /// ### What it does + /// Checks for printing on *stderr*. The purpose of this lint /// is to catch debugging remnants. /// - /// **Why is this bad?** People often print on *stderr* while debugging an + /// ### Why is this bad? + /// People often print on *stderr* while debugging an /// application and might forget to remove those prints afterward. /// - /// **Known problems:** Only catches `eprint!` and `eprintln!` calls. + /// ### Known problems + /// Only catches `eprint!` and `eprintln!` calls. /// - /// **Example:** + /// ### Example /// ```rust /// eprintln!("Hello world!"); /// ``` @@ -97,13 +103,15 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** Checks for use of `Debug` formatting. The purpose of this + /// ### What it does + /// Checks for use of `Debug` formatting. The purpose of this /// lint is to catch debugging remnants. /// - /// **Why is this bad?** The purpose of the `Debug` trait is to facilitate + /// ### Why is this bad? + /// The purpose of the `Debug` trait is to facilitate /// debugging Rust code. It should not be used in user-facing output. /// - /// **Example:** + /// ### Example /// ```rust /// # let foo = "bar"; /// println!("{:?}", foo); @@ -114,16 +122,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** This lint warns about the use of literals as `print!`/`println!` args. + /// ### What it does + /// This lint warns about the use of literals as `print!`/`println!` args. /// - /// **Why is this bad?** Using literals as `println!` args is inefficient + /// ### Why is this bad? + /// Using literals as `println!` args is inefficient /// (c.f., https://github.com/matthiaskrgr/rust-str-bench) and unnecessary /// (i.e., just put the literal in the format string) /// - /// **Known problems:** Will also warn with macro calls as arguments that expand to literals + /// ### Known problems + /// Will also warn with macro calls as arguments that expand to literals /// -- e.g., `println!("{}", env!("FOO"))`. /// - /// **Example:** + /// ### Example /// ```rust /// println!("{}", "foo"); /// ``` @@ -137,14 +148,14 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** This lint warns when you use `writeln!(buf, "")` to + /// ### What it does + /// This lint warns when you use `writeln!(buf, "")` to /// print a newline. /// - /// **Why is this bad?** You should use `writeln!(buf)`, which is simpler. + /// ### Why is this bad? + /// You should use `writeln!(buf)`, which is simpler. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # use std::fmt::Write; /// # let mut buf = String::new(); @@ -160,16 +171,16 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** This lint warns when you use `write!()` with a format + /// ### What it does + /// This lint warns when you use `write!()` with a format /// string that /// ends in a newline. /// - /// **Why is this bad?** You should use `writeln!()` instead, which appends the + /// ### Why is this bad? + /// You should use `writeln!()` instead, which appends the /// newline. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// # use std::fmt::Write; /// # let mut buf = String::new(); @@ -186,16 +197,19 @@ declare_clippy_lint! { } declare_clippy_lint! { - /// **What it does:** This lint warns about the use of literals as `write!`/`writeln!` args. + /// ### What it does + /// This lint warns about the use of literals as `write!`/`writeln!` args. /// - /// **Why is this bad?** Using literals as `writeln!` args is inefficient + /// ### Why is this bad? + /// Using literals as `writeln!` args is inefficient /// (c.f., https://github.com/matthiaskrgr/rust-str-bench) and unnecessary /// (i.e., just put the literal in the format string) /// - /// **Known problems:** Will also warn with macro calls as arguments that expand to literals + /// ### Known problems + /// Will also warn with macro calls as arguments that expand to literals /// -- e.g., `writeln!(buf, "{}", env!("FOO"))`. /// - /// **Example:** + /// ### Example /// ```rust /// # use std::fmt::Write; /// # let mut buf = String::new(); diff --git a/clippy_lints/src/zero_div_zero.rs b/clippy_lints/src/zero_div_zero.rs index a1ea743ba804d..b29ced28ac491 100644 --- a/clippy_lints/src/zero_div_zero.rs +++ b/clippy_lints/src/zero_div_zero.rs @@ -6,13 +6,13 @@ use rustc_lint::{LateContext, LateLintPass}; use rustc_session::{declare_lint_pass, declare_tool_lint}; declare_clippy_lint! { - /// **What it does:** Checks for `0.0 / 0.0`. + /// ### What it does + /// Checks for `0.0 / 0.0`. /// - /// **Why is this bad?** It's less readable than `f32::NAN` or `f64::NAN`. + /// ### Why is this bad? + /// It's less readable than `f32::NAN` or `f64::NAN`. /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Example /// ```rust /// // Bad /// let nan = 0.0f32 / 0.0; diff --git a/clippy_lints/src/zero_sized_map_values.rs b/clippy_lints/src/zero_sized_map_values.rs index d6a8112218f13..2fbe27f94798b 100644 --- a/clippy_lints/src/zero_sized_map_values.rs +++ b/clippy_lints/src/zero_sized_map_values.rs @@ -10,18 +10,19 @@ use rustc_target::abi::LayoutOf as _; use rustc_typeck::hir_ty_to_ty; declare_clippy_lint! { - /// **What it does:** Checks for maps with zero-sized value types anywhere in the code. + /// ### What it does + /// Checks for maps with zero-sized value types anywhere in the code. /// - /// **Why is this bad?** Since there is only a single value for a zero-sized type, a map + /// ### Why is this bad? + /// Since there is only a single value for a zero-sized type, a map /// containing zero sized values is effectively a set. Using a set in that case improves /// readability and communicates intent more clearly. /// - /// **Known problems:** + /// ### Known problems /// * A zero-sized type cannot be recovered later if it contains private fields. /// * This lints the signature of public items /// - /// **Example:** - /// + /// ### Example /// ```rust /// # use std::collections::HashMap; /// fn unique_words(text: &str) -> HashMap<&str, ()> { diff --git a/doc/adding_lints.md b/doc/adding_lints.md index 5a06afedbf4c2..f2260c3d1a267 100644 --- a/doc/adding_lints.md +++ b/doc/adding_lints.md @@ -11,6 +11,7 @@ because that's clearly a non-descriptive name. - [Setup](#setup) - [Getting Started](#getting-started) - [Testing](#testing) + - [Cargo lints](#cargo-lints) - [Rustfix tests](#rustfix-tests) - [Edition 2018 tests](#edition-2018-tests) - [Testing manually](#testing-manually) @@ -179,14 +180,11 @@ the auto-generated lint declaration to have a real description, something like t ```rust declare_clippy_lint! { - /// **What it does:** + /// ### What it does /// - /// **Why is this bad?** - /// - /// **Known problems:** None. - /// - /// **Example:** + /// ### Why is this bad? /// + /// ### Example /// ```rust /// // example code /// ``` @@ -487,13 +485,13 @@ Please document your lint with a doc comment akin to the following: ```rust declare_clippy_lint! { - /// **What it does:** Checks for ... (describe what the lint matches). - /// - /// **Why is this bad?** Supply the reason for linting the code. + /// ### What it does + /// Checks for ... (describe what the lint matches). /// - /// **Known problems:** None. (Or describe where it could go wrong.) + /// ### Why is this bad? + /// Supply the reason for linting the code. /// - /// **Example:** + /// ### Example /// /// ```rust,ignore /// // Bad From 9bc5803195f75895614feae27607564da01d100a Mon Sep 17 00:00:00 2001 From: flip1995 <philipp.krones@embecosm.com> Date: Wed, 28 Jul 2021 13:51:16 +0200 Subject: [PATCH 2/2] Fix last occurence of **What it does:** --- clippy_lints/src/utils/internal_lints/metadata_collector.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/clippy_lints/src/utils/internal_lints/metadata_collector.rs b/clippy_lints/src/utils/internal_lints/metadata_collector.rs index 3244677b301b7..3f5abf3fb8f06 100644 --- a/clippy_lints/src/utils/internal_lints/metadata_collector.rs +++ b/clippy_lints/src/utils/internal_lints/metadata_collector.rs @@ -139,7 +139,7 @@ declare_clippy_lint! { /// "line": 1 /// }, /// "group": "clippy::internal", - /// "docs": " **What it does:** Collects metadata about clippy lints for the website. [...] " + /// "docs": " ### What it does\nCollects metadata about clippy lints for the website. [...] " /// } /// ``` pub INTERNAL_METADATA_COLLECTOR,