diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md index cb3b4b404f838..33dbbf7e22af2 100644 --- a/src/doc/rustc-dev-guide/src/SUMMARY.md +++ b/src/doc/rustc-dev-guide/src/SUMMARY.md @@ -132,6 +132,7 @@ - [Creating Errors With SessionDiagnostic](./diagnostics/sessiondiagnostic.md) - [`LintStore`](./diagnostics/lintstore.md) - [Diagnostic Codes](./diagnostics/diagnostic-codes.md) + - [Diagnostic Items](./diagnostics/diagnostic-items.md) # MIR to Binaries diff --git a/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-items.md b/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-items.md new file mode 100644 index 0000000000000..efaa01cf396f1 --- /dev/null +++ b/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-items.md @@ -0,0 +1,146 @@ +# Diagnostic Items + +## Background + +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 and can lead to misclassifications in some edge cases. +To counteract this, rustc has introduced diagnostic items that are used to identify types via +[`Symbol`]s. + +## How To Find Diagnostic Items + +Diagnostic items are added to items inside `rustc`/`std`/`core` 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 errors during tests. A definition often looks like this: + +```rs +// This is the diagnostic item for this type vvvvvvv +#[cfg_attr(not(test), rustc_diagnostic_item = "Penguin")] +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 [*Using Diagnostic Items*](#using-diagnostic-items). + +## How To Add 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 string via the + `rustc_diagnostic_item` attribute. This can sometimes cause compilation errors while running + tests. These errors can be avoided by using the `cfg_attr` attribute with the `not(test)` + condition (it's fine adding then for all `rustc_diagnostic_item` attributes as a preventive + manner). At the end, it should look like this: + + ```rs + // This will be the new diagnostic item vvv + #[cfg_attr(not(test), rustc_diagnostic_item = "Cat")] + struct Cat; + ``` + + For the naming conventions of diagnostic items, please refer to + [*Naming Conventions*](#naming-conventions). + +2. As of August 2021 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. + +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.) + +## 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: + +* 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. +* 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`) +* 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. + +## How To Use 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`] 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. + +### Check For A Type + +```rust +use rustc_span::symbol::sym; + +/// This example checks if the given type (`ty`) has the type `HashMap` using +/// `TyCtxt::is_diagnostic_item()` +fn example_1(cx: &LateContext<'_>, ty: Ty<'_>) -> bool { + match ty.kind() { + ty::Adt(adt, _) => cx.tcx.is_diagnostic_item(sym::HashMap, adt.did), + _ => false, + } +} +``` + +### Check 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. +fn is_diag_trait_item( + cx: &LateContext<'_>, + def_id: DefId, + diag_item: Symbol +) -> bool { + if let Some(trait_did) = cx.tcx.trait_of_item(def_id) { + return cx.tcx.is_diagnostic_item(diag_item, trait_did); + } + false +} +``` + +### 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 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 :) + +* [rust#60966]: The Rust PR that introduced diagnostic items +* [rust-clippy#5393]: Clippy's tracking issue for moving away from hard coded paths to + diagnostic item + + + +[`rustc_span::symbol::sym`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/symbol/sym/index.html +[`Symbol`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/symbol/struct.Symbol.html +[`DefId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.DefId.html +[`TyCtxt::get_diagnostic_item()`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.get_diagnostic_item +[`TyCtxt::is_diagnostic_item()`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.is_diagnostic_item +[`TyCtxt::associated_items()`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.associated_items +[`AssocItems`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/assoc/struct.AssocItems.html +[`clippy_utils::ty::get_iterator_item_ty()`]: https://github.com/rust-lang/rust-clippy/blob/305177342fbc622c0b3cb148467bab4b9524c934/clippy_utils/src/ty.rs#L55-L72 +[clippy-Common-tools-for-writing-lints]: https://github.com/rust-lang/rust-clippy/blob/master/doc/common_tools_writing_lints.md +[rust#60966]: https://github.com/rust-lang/rust/pull/60966 +[rust-clippy#5393]: https://github.com/rust-lang/rust-clippy/issues/5393