Document lint configuration values in Clippy's book

[xFrednet]

We have a few lints with configuration values, like borrow_as_ptr. We want to increase the visibility of these config values, to encourage the use of them.

As part of this, we'd like a chapter about configuring lints and having a list of available configurations with links to Clippy's lint list.

Tasks:

• Write how a user can add configurations: See Current docs
• Generate list of configurations. This can be done in Clippy's metadata collector. https://github.com/rust-lang/rust-clippy/blob/master/clippy_lints/src/utils/internal_lints/metadata_collector.rs
• Include the generated list in the book
• Be happy!

---

I'm open to mentoring this issue :)

CC: #9880

[tylerjw]

@rustbot claim

I want to work on this issue. This will be my second PR. Thank you for all the help on the first one.

[xFrednet]

Awesome! Please reach out if you need any assistance :)

[tylerjw]

On the first task; here is what is in the README:

Would you like something different than this?

The readme links to this: https://rust-lang.github.io/rust-clippy/master/index.html#Configuration

[tylerjw]

This is also in the book:

https://doc.rust-lang.org/nightly/clippy/configuration.html

[tylerjw]

Are you hoping for something similar to what is in the rustc book here: https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html

[xFrednet]

Hey @tylerjw, thank you for picking up this issue!

Would you like something different than this?

No, that is the basic information where to put the files and the basic structure. Though, looking at it, I'd suggest updating the variable in question. cognitive-complexity-threshold has been deprecated AFAIK.

Then there is a new convention (Or I'm trying to make it a convention) for list variables like disallowed-names. Default list can either be replaced, as shown above or extended, if ".." is included as a variable. So

disallowed-names = ["Test"] # -> ["Test"]
disallowed-names = ["Test", ".."] # -> ["Test", "foo", "baz", "quux"]

It would be cool, if this could be mentioned as part of the description as well.

Are you hoping for something similar to what is in the rustc book here

Yes, that was the goal of this issue. Basically, a list, with all configurations, their default values and which lints are effected. The lints should ideally also be links to Clippy's lint list. Ideally, this list should be generated automatically, that's why the metadata collection lint is linked above. You can use cargo collect-metadata to run it :)

[tylerjw]

Deleteing my comment because I went and read the details on disallowed_names. I now understand that the ".." syntax is for extending the default configuration of this variable.

[tylerjw]

@xFrednet I'm still working on the learning I need to do in order to make the more significant PR to the book but in the meantime I documented the config behavior you noted in your comment here: #10190

[tylerjw]

As to cognitive-complexity-threshold I see it is in the nursery, and there are a few issues where people comment that it is not well documented. Should I just remove the mention of it from the docs here?

[tylerjw]

Here is a PR with both the change to remove cognitive-complexity-threshold and add a note about extending default values: #10199

[tylerjw]

If you saw this comment before I updated it, there were two options. I tried implementing both, and one proved to be much easier and had much less code, so I went with that approach. I'll submit a PR soon so you can play with it and see what you think.

Here is my draft idea for the new config page in the docs:

Configuration Options

Option	Default	Description	Lints
arithmetic-side-effects-allowed	{}	Suppress checking of the passed type names in all types of operations	arithmetic_side_effects
arithmetic-side-effects-allowed-binary	[]	Suppress checking of the passed type pair names in binary operations like addition or multiplication	arithmetic_side_effects
arithmetic-side-effects-allowed-unary	{}	Suppress checking of the passed type names in unary operations like "negation" (-)	arithmetic_side_effects
avoid-breaking-exported-api	true	Suppress lints whenever the suggested change would cause breakage for other crates	enum_variant_names large_types_passed_by_value trivially_copy_pass_by_ref unnecessary_wraps unused_self upper_case_acronyms wrong_self_convention box_collection redundant_allocation rc_buffer vec_box option_option linkedlist rc_mutex
msrv	None	The minimum rust version that the project supports	manual_split_once manual_str_repeat cloned_instead_of_copied redundant_field_names redundant_static_lifetimes filter_map_next checked_conversions manual_range_contains use_self mem_replace_with_default manual_non_exhaustive option_as_ref_deref map_unwrap_or match_like_matches_macro manual_strip missing_const_for_fn unnested_or_patterns from_over_into ptr_as_ptr if_then_some_else_none approx_constant deprecated_cfg_attr index_refutable_slice map_clone borrow_as_ptr manual_bits err_expect cast_abs_to_unsigned uninlined_format_args manual_clamp manual_let_else unchecked_duration_subtraction
cognitive-complexity-threshold	25	The maximum cognitive complexity a function can have	cognitive_complexity
disallowed-names	["foo", "baz", "quux"]	The list of disallowed names to lint about	disallowed_names
doc-valid-idents	["KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "DirectX", "ECMAScript", "GPLv2", "GPLv3", "GitHub", "GitLab", "IPv4", "IPv6", "ClojureScript", "CoffeeScript", "JavaScript", "PureScript", "TypeScript", "NaN", "NaNs", "OAuth", "GraphQL", "OCaml", "OpenGL", "OpenMP", "OpenSSH", "OpenSSL", "OpenStreetMap", "OpenDNS", "WebGL", "TensorFlow", "TrueType", "iOS", "macOS", "FreeBSD", "TeX", "LaTeX", "BibTeX", "BibLaTeX", "MinGW", "CamelCase"]	The list of words this lint should not consider as identifiers needing ticks	doc_markdown
too-many-arguments-threshold	7	The maximum number of argument a function or method can have	too_many_arguments
type-complexity-threshold	250	The maximum complexity a type can have	type_complexity
single-char-binding-names-threshold	4	The maximum number of single char bindings a scope may have	many_single_char_names
too-large-for-stack	200	The maximum size of objects (in bytes) that will be linted	boxed_local useless_vec
enum-variant-name-threshold	3	The minimum number of enum variants for the lints about variant names to trigger	enum_variant_names
enum-variant-size-threshold	200	The maximum size of an enum's variant to avoid box suggestion	large_enum_variant
verbose-bit-mask-threshold	1	The maximum allowed size of a bit mask before suggesting to use 'trailing_zeros'	verbose_bit_mask
literal-representation-threshold	16384	The lower bound for linting decimal literals	decimal_literal_representation
trivial-copy-size-limit	None	The maximum size (in bytes) to consider a Copy type for passing by value instead of by reference	trivially_copy_pass_by_ref
pass-by-value-size-limit	256	The minimum size (in bytes) to consider a type for passing by reference instead of by value	large_type_pass_by_move
too-many-lines-threshold	100	The maximum number of lines a function or method can have	too_many_lines
array-size-threshold	512000	The maximum allowed size for arrays on the stack	large_stack_arrays large_const_arrays
vec-box-size-threshold	4096	The size of the boxed type in bytes, where boxing in a Vec is allowed	vec_box
max-trait-bounds	3	The maximum number of bounds a trait can have to be linted	type_repetition_in_bounds
max-struct-bools	3	The maximum number of bool fields a struct can have	struct_excessive_bools
max-fn-params-bools	3	The maximum number of bool parameters a function can have	fn_params_excessive_bools
warn-on-all-wildcard-imports	false	Whether to allow certain wildcard imports (prelude, super in tests)	wildcard_imports
disallowed-macros	[]	The list of disallowed macros, written as fully qualified paths	disallowed_macros
disallowed-methods	[]	The list of disallowed methods, written as fully qualified paths	disallowed_methods
disallowed-types	[]	The list of disallowed types, written as fully qualified paths	disallowed_types
unreadable-literal-lint-fractions	true	Should the fraction of a decimal be linted to include separators	unreadable_literal
upper-case-acronyms-aggressive	false	Enables verbose mode	upper_case_acronyms
matches-for-let-else	WellKnownTypes	Whether the matches should be considered by the lint, and whether there should be filtering for common types	manual_let_else
cargo-ignore-publish	false	For internal testing only, ignores the current publish settings in the Cargo manifest	_cargo_common_metadata
standard-macro-braces	[]	Enforce the named macros always use the braces specified	nonstandard_macro_braces
enforced-import-renames	[]	The list of imports to always rename, a fully qualified path followed by the rename	missing_enforced_import_renames
allowed-scripts	["Latin"]	The list of unicode scripts allowed to be used in the scope	disallowed_script_idents
enable-raw-pointer-heuristic-for-send	true	Whether to apply the raw pointer heuristic to determine if a type is Send	non_send_fields_in_send_ty
max-suggested-slice-pattern-length	3	When Clippy suggests using a slice pattern, this is the maximum number of elements allowed in the slice pattern that is suggested	index_refutable_slice
await-holding-invalid-types	[]	[ERROR] MALFORMED DOC COMMENT
max-include-file-size	1000000	The maximum size of a file included via include_bytes!() or include_str!(), in bytes	large_include_file
allow-expect-in-tests	false	Whether expect should be allowed within #[cfg(test)]	expect_used
allow-unwrap-in-tests	false	Whether unwrap should be allowed in test cfg	unwrap_used
allow-dbg-in-tests	false	Whether dbg! should be allowed in test functions	dbg_macro
allow-print-in-tests	false	Whether print macros (ex	print_stdout print_stderr
large-error-threshold	128	The maximum size of the Err-variant in a Result returned from a function	result_large_err
ignore-interior-mutability	["bytes::Bytes"]	A list of paths to types that should be treated like Arc, i	mutable_key
allow-mixed-uninlined-format-args	true	Whether to allow mixed uninlined format args, e	uninlined_format_args
suppress-restriction-lint-in-const	false	In same cases the restructured operation might not be unavoidable, as the suggested counterparts are unavailable in constant code	indexing_slicing

[xFrednet]

I saw this comment before the PR. ^^

The output looks really cool. The only NIT is that I'd like the description column to be wider than it currently is. Maybe we can add <br> behind each lint name and config element? The question is also if we can have paragraphs. It might actually be better to have them more layout like this:

## <config-name>

<description>

<default>

<lints>

Even though I like the table look of your suggestion a lot. Would you be okay with creating a prototype for the example above? Then we can make screenshots and ask for more feedback on Zulip :)