Documenting diagnostic items with their usage and naming conventions

[xFrednet]

🖼️ Rendered 🖼️

This PR documents the following aspects about diagnostic items:

• Background
• How To Find Diagnostic Items
• How To Add Diagnostic Items
• Naming Conventions
• How To Use Diagnostic Items
  • Check For A Type
  • Check For A Trait Implementation
  • Associated Types
  • Usage In Clippy
• Related Issues

I focussed on general information that is true for both, writing lints in rustc and Clippy. The documentation still contains some related links and comments about the usage in Clippy. I hope that this is a nice balance.

cc: @rust-lang/clippy, @rust-lang/wg-diagnostics

---

Meta

Closes #1188

Also referencing rust-lang/rust-clippy#5393 for good measure. Hello Clippy repo!

---

That's it, I hope everyone is having a great day. 🙃

[jyn514]

This looks great :) the only other thing I'd want to see is when to use lang_items over diagnostic items, but that doesn't have to block this.

[xFrednet]

the only other thing I'd want to see is when to use lang_items over diagnostic items

I've seen a comment in Clippy's documentation regarding this, but I'm honestly not sure what the guidelines are. Could you elaborate on this a bit more? @jyn514 🙃

[xFrednet]

Thank you for the review @camelid, you found my usual spelling mistakes ^^.

[jyn514]

the only other thing I'd want to see is when to use lang_items over diagnostic items

I've seen a comment in Clippy's documentation regarding this, but I'm honestly not sure what the guidelines are. Could you elaborate on this a bit more? @jyn514 🙃

Oh, that wasn't meant to be a gotcha question - I honestly don't know ( #1119 (comment)). If you're not sure either we can leave it out until we hear from @nikomatsakis.

[xFrednet]

No problem, I didn't take it that way 🙃

we can leave it out until we hear from @nikomatsakis.

Sounds like a plan, I would leave the PR open a little longer, about a week, to give the named parties in cc some time as well 🙃

[nikomatsakis]

I think the answer is:

• Use a lang item if you are changing what code is accepted or what the code does when it is compiled
• Use a diagnostic item if you are only trying to emit better diagnostics

[camsteffen]

Just a Clippy dev perspective:

I think there is a potential answer of - Clippy should just use diagnostic items for consistency and simplicity, even if it means that some items are both a lang item and a diagnostic item. The answer I have gone with thus far is - prefer lang items in Clippy if they happen to be available. I guess the only reason I prefer lang items is that they seem a little less error prone since they are strongly typed (I wonder if diagnostic items could be granted a similar API).

[jyn514]

@camsteffen you don't want the API to be strongly typed - that means you have to add the diagnostic items in both the compiler and the standard library, which hurts compile times. You'd still have to handle the diagnostic item being missing either way so I don't know how much it's buying you.

[camsteffen]

As a concrete, hypothetical example, with diagnostic items you might mistakenly use sym::Vec instead of sym::vec_type.

[llogiq]

As a non-hypothetical example, I recently (in some unfinished code) wanted to match a str type, and the str_type diagnostic item didn't do this, so I got the lang_item::str instead.

In general, people will try things until something works.

[xFrednet]

My understanding from @nikomatsakis comment is, that diagnostic items should be domain specific to diagnostics. This is implied for me by the location Errors and Lints > Diagnostic items and the focus on lints in the documentation. However, I can add a comment about :)

I agree here with @llogiq that contributors will most likely just take what's available. I personally prefer diagnostic items in Clippy for consistency, as @camsteffen said. Additionally, diagnostic items are easier to add, PRs for those are usually merged quite quickly.

even if it means that some items are both a lang item and a diagnostic item

FYI: Rust already has some items which have both a lang and diagnostic item attached to them, and everything seems to be working well.

[jyn514]

Well, in any case this PR is a great improvement as-is. @camelid wanted to review the wording in detail but otherwise it seems good to me :)

[nikomatsakis]

I don't have a problem with having both a lang and a diagnostic item. I am also ok with people using lang items if they are available, tbh. I think I would not want a language semantics change using a diagnostic item, however.

[Manishearth]

Yeah, this is in line with my expectation as well.

[camelid]

Thanks!