From 7f2dc2387e2df50d403e705b4f4113c63bd99b85 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Fri, 12 Aug 2022 15:50:06 +0200 Subject: [PATCH 01/10] found it in alloc too --- src/diagnostics/diagnostic-items.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/diagnostics/diagnostic-items.md b/src/diagnostics/diagnostic-items.md index d83f079d5..f778e6875 100644 --- a/src/diagnostics/diagnostic-items.md +++ b/src/diagnostics/diagnostic-items.md @@ -7,7 +7,7 @@ rustc has introduced diagnostic items that are used to identify types via [`Symbol`]s. ## Finding diagnostic items -Diagnostic items are added to items inside `rustc`/`std`/`core` with the +Diagnostic items are added to items inside `rustc`/`std`/`core`/`alloc` with the `rustc_diagnostic_item` attribute. The item for a specific type can be found by opening the source code in the documentation and looking for this attribute. Note that it's often added with the `cfg_attr` attribute to avoid compilation From 8696894bae61a5a34dd75087e5c53272e390663d Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Fri, 12 Aug 2022 15:55:55 +0200 Subject: [PATCH 02/10] fix anchor link --- src/diagnostics/diagnostic-items.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/diagnostics/diagnostic-items.md b/src/diagnostics/diagnostic-items.md index f778e6875..c809927af 100644 --- a/src/diagnostics/diagnostic-items.md +++ b/src/diagnostics/diagnostic-items.md @@ -19,10 +19,12 @@ errors during tests. A definition often looks like this: struct Penguin; ``` -Diagnostic items are usually only added to traits, types and standalone -functions. If the goal is to check for an associated type or method, please use -the diagnostic item of the item and reference [*How To Use Diagnostic -Items*](#how-to-use-diagnostic-items). +Diagnostic items are usually only added to traits, +types, +and standalone functions. +If the goal is to check for an associated type or method, +please use the diagnostic item of the item and reference +[*Using Diagnostic Items*](#using-diagnostic-items). ## Adding diagnostic items A new diagnostic item can be added with these two steps: From b2e6a285b0afb03f25ac85d9252031fdcfe6c4d5 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Fri, 12 Aug 2022 15:59:52 +0200 Subject: [PATCH 03/10] missing commas --- src/diagnostics/diagnostic-items.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/diagnostics/diagnostic-items.md b/src/diagnostics/diagnostic-items.md index c809927af..bd037fb40 100644 --- a/src/diagnostics/diagnostic-items.md +++ b/src/diagnostics/diagnostic-items.md @@ -46,9 +46,10 @@ A new diagnostic item can be added with these two steps: [*Naming Conventions*](#naming-conventions). 2. As of February 2022, diagnostic items in code are - accessed via symbols in [`rustc_span::symbol::sym`]. To add your newly - created diagnostic item simply open the module file and add the name (In - this case `Cat`) at the correct point in the list. + accessed via symbols in [`rustc_span::symbol::sym`]. + To add your newly-created diagnostic item, + simply open the module file, + and add the name (In this case `Cat`) at the correct point in the list. Now you can create a pull request with your changes. :tada: (Note that when using diagnostic items in other projects like Clippy, it might take some time From 68d3ab44f801bc2da7fc846dbc43f03fdecac70a Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Fri, 12 Aug 2022 16:14:50 +0200 Subject: [PATCH 04/10] date-check: diagnostic-items --- src/diagnostics/diagnostic-items.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/diagnostics/diagnostic-items.md b/src/diagnostics/diagnostic-items.md index bd037fb40..a8bb81f40 100644 --- a/src/diagnostics/diagnostic-items.md +++ b/src/diagnostics/diagnostic-items.md @@ -45,8 +45,9 @@ A new diagnostic item can be added with these two steps: For the naming conventions of diagnostic items, please refer to [*Naming Conventions*](#naming-conventions). -2. As of February 2022, diagnostic items in code are - accessed via symbols in [`rustc_span::symbol::sym`]. +2. + Diagnostic items in code are accessed via symbols in + [`rustc_span::symbol::sym`]. To add your newly-created diagnostic item, simply open the module file, and add the name (In this case `Cat`) at the correct point in the list. From ede639147568bca9b3ed828f456dba76824c5599 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Fri, 12 Aug 2022 16:17:58 +0200 Subject: [PATCH 05/10] style --- src/diagnostics/diagnostic-items.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/diagnostics/diagnostic-items.md b/src/diagnostics/diagnostic-items.md index a8bb81f40..d85e005a9 100644 --- a/src/diagnostics/diagnostic-items.md +++ b/src/diagnostics/diagnostic-items.md @@ -52,9 +52,11 @@ A new diagnostic item can be added with these two steps: simply open the module file, and add the name (In this case `Cat`) at the correct point in the list. -Now you can create a pull request with your changes. :tada: (Note that when -using diagnostic items in other projects like Clippy, it might take some time -until the repos get synchronized.) +Now you can create a pull request with your changes. :tada: + +> NOTE: +> When using diagnostic items in other projects like Clippy, +> it might take some time until the repos get synchronized. ## Naming conventions Diagnostic items don't have a set in stone naming convention yet. These are From f3ee8674de89148b98c938f6cca6345281208da5 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Fri, 12 Aug 2022 16:30:59 +0200 Subject: [PATCH 06/10] room to breath --- src/diagnostics/diagnostic-items.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/diagnostics/diagnostic-items.md b/src/diagnostics/diagnostic-items.md index d85e005a9..0228b3971 100644 --- a/src/diagnostics/diagnostic-items.md +++ b/src/diagnostics/diagnostic-items.md @@ -1,4 +1,5 @@ # Diagnostic Items + While writing lints it's common to check for specific types, traits and functions. This raises the question on how to check for these. Types can be checked by their complete type path. However, this requires hard coding paths @@ -7,6 +8,7 @@ rustc has introduced diagnostic items that are used to identify types via [`Symbol`]s. ## Finding diagnostic items + Diagnostic items are added to items inside `rustc`/`std`/`core`/`alloc` with the `rustc_diagnostic_item` attribute. The item for a specific type can be found by opening the source code in the documentation and looking for this attribute. @@ -27,6 +29,7 @@ please use the diagnostic item of the item and reference [*Using Diagnostic Items*](#using-diagnostic-items). ## Adding diagnostic items + A new diagnostic item can be added with these two steps: 1. Find the target item inside the Rust repo. Now add the diagnostic item as a @@ -59,6 +62,7 @@ Now you can create a pull request with your changes. :tada: > it might take some time until the repos get synchronized. ## Naming conventions + Diagnostic items don't have a set in stone naming convention yet. These are some guidelines that should be used for the future, but might differ from existing names: @@ -78,6 +82,7 @@ existing names: modules would therefore most likely to be counterproductive. ## Using diagnostic items + In rustc, diagnostic items are looked up via [`Symbol`]s from inside the [`rustc_span::symbol::sym`] module. These can then be mapped to [`DefId`]s using [`TyCtxt::get_diagnostic_item()`] or checked if they match a [`DefId`] @@ -88,6 +93,7 @@ instance when compiling with `#[no_std]`. All following examples are based on [`DefId`]s and their usage. ### Example: Checking for a type + ```rust use rustc_span::symbol::sym; @@ -102,6 +108,7 @@ fn example_1(cx: &LateContext<'_>, ty: Ty<'_>) -> bool { ``` ### Example: Checking for a trait implementation + ```rust /// This example checks if a given [`DefId`] from a method is part of a trait /// implementation defined by a diagnostic item. @@ -118,6 +125,7 @@ fn is_diag_trait_item( ``` ### Associated Types + Associated types of diagnostic items can be accessed indirectly by first getting the [`DefId`] of the trait and then calling [`TyCtxt::associated_items()`]. This returns an [`AssocItems`] object which can @@ -125,12 +133,14 @@ be used for further checks. Checkout [`clippy_utils::ty::get_iterator_item_ty()`] for an example usage of this. ### Usage in Clippy + Clippy tries to use diagnostic items where possible and has developed some wrapper and utility functions. Please also refer to its documentation when using diagnostic items in Clippy. (See [*Common tools for writing lints*][clippy-Common-tools-for-writing-lints].) ## Related issues + This lists some related issues. These are probably only interesting to people who really want to take a deep dive into the topic :) From 8ed30f807e618e9253f5882ded54295ce2545d62 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Fri, 12 Aug 2022 16:33:06 +0200 Subject: [PATCH 07/10] more simple --- src/diagnostics/diagnostic-items.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/diagnostics/diagnostic-items.md b/src/diagnostics/diagnostic-items.md index 0228b3971..09b9b99ef 100644 --- a/src/diagnostics/diagnostic-items.md +++ b/src/diagnostics/diagnostic-items.md @@ -63,9 +63,9 @@ Now you can create a pull request with your changes. :tada: ## Naming conventions -Diagnostic items don't have a set in stone naming convention yet. These are -some guidelines that should be used for the future, but might differ from -existing names: +Diagnostic items don't have a naming convention yet. +Following are some guidelines that should be used in future, +but might differ from existing names: * Types, traits and enums are named using UpperCamelCase (Examples: `Iterator`, * `HashMap`, ...) From 5f28d889542f622187a8a1fecae1f0262fd9d97e Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Fri, 12 Aug 2022 16:43:46 +0200 Subject: [PATCH 08/10] reformat section, and minor fixes --- src/diagnostics/diagnostic-items.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/src/diagnostics/diagnostic-items.md b/src/diagnostics/diagnostic-items.md index 09b9b99ef..2ee0723bd 100644 --- a/src/diagnostics/diagnostic-items.md +++ b/src/diagnostics/diagnostic-items.md @@ -67,19 +67,22 @@ Diagnostic items don't have a naming convention yet. Following are some guidelines that should be used in future, but might differ from existing names: -* Types, traits and enums are named using UpperCamelCase (Examples: `Iterator`, -* `HashMap`, ...) -* For type names that are used multiple times like `Writer` it's good to choose - a more precise name, maybe by adding the module to it. (Example: `IoWriter`) -* Associated items should not get their own diagnostic items, but instead be - accessed indirectly by the diagnostic item of the type they're originating - from. +* Types, traits, and enums are named using UpperCamelCase + (Examples: `Iterator` and `HashMap`) +* For type names that are used multiple times, + like `Writer`, + it's good to choose a more precise name, + maybe by adding the module to it + (Example: `IoWriter`) +* Associated items should not get their own diagnostic items, + but instead be accessed indirectly by the diagnostic item + of the type they're originating from. * Freestanding functions like `std::mem::swap()` should be named using - `snake_case` with one important (export) module as a prefix (Example: - `mem_swap`, `cmp_max`) + `snake_case` with one important (export) module as a prefix + (Examples: `mem_swap` and `cmp_max`) * Modules should usually not have a diagnostic item attached to them. - Diagnostic items were added to avoid the usage of paths, using them on - modules would therefore most likely to be counterproductive. + Diagnostic items were added to avoid the usage of paths, + and using them on modules would therefore most likely be counterproductive. ## Using diagnostic items From 639671a4be66e4d1f26db5325d5e2a427c2801fd Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Fri, 12 Aug 2022 16:45:10 +0200 Subject: [PATCH 09/10] missing word --- src/diagnostics/diagnostic-items.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/diagnostics/diagnostic-items.md b/src/diagnostics/diagnostic-items.md index 2ee0723bd..1d467f972 100644 --- a/src/diagnostics/diagnostic-items.md +++ b/src/diagnostics/diagnostic-items.md @@ -92,8 +92,8 @@ using [`TyCtxt::get_diagnostic_item()`] or checked if they match a [`DefId`] using [`TyCtxt::is_diagnostic_item()`]. When mapping from a diagnostic item to a [`DefId`], the method will return a `Option`. This can be `None` if either the symbol isn't a diagnostic item or the type is not registered, for -instance when compiling with `#[no_std]`. All following examples are based on -[`DefId`]s and their usage. +instance when compiling with `#[no_std]`. +All the following examples are based on [`DefId`]s and their usage. ### Example: Checking for a type From bc02fa30e7ce2e2ea50b1c07ffe47c879900f506 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Fri, 12 Aug 2022 16:47:04 +0200 Subject: [PATCH 10/10] repetition --- src/diagnostics/diagnostic-items.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/diagnostics/diagnostic-items.md b/src/diagnostics/diagnostic-items.md index 1d467f972..dcaba533e 100644 --- a/src/diagnostics/diagnostic-items.md +++ b/src/diagnostics/diagnostic-items.md @@ -144,7 +144,7 @@ lints*][clippy-Common-tools-for-writing-lints].) ## Related issues -This lists some related issues. These are probably only interesting to people +These are probably only interesting to people who really want to take a deep dive into the topic :) * [rust#60966]: The Rust PR that introduced diagnostic items