Document lang items

[jyn514]

This is mostly the text from #978 with the exhaustive list of lang items removed.

cc @MikailBag, @nikomatsakis, @camelid

[nikomatsakis]

This is nice. I want to cc @roxelo who recently had to add lang-items and so forth. Would this text have been helpful? Are there things you had to figure out that are worth including?

One thing I would like to see:

• Document how you get the def-id for a lang-item with a small example
• Talk more about why it returns Option and what you should do if the result is None -- the answer is typically not unwrap but try to recover in some sensible way.

[camelid]

I left a few copy edits and clarifications of things that seemed ambiguous.

[camelid]

Suggested change

	- An auto-generated list with source locations by using ripgrep: `rg '#\[.*lang =' library/`
	- An auto-generated list with source locations in the standard library by using ripgrep: `rg '#\[.*lang =' library/`

[jyn514]

I don't think this is more clear. I could say "A list of items in the standard library, along with their sources, by using ripgrep" if you like.

[camelid]

I suggested that just to make it clear that language items can be defined outside of the standard library, and that these source locations are specifically the ones defined by the standard library.

[jyn514]

I think that's too much nuance to pack into 4 words. Defining lang-items outside the standard library is pretty rare - I can add a section if you like, but I don't think it belongs here.

[jyn514]

@nikomatsakis when should someone create a lang item instead of using a rustc_diagnostic_item? The only difference I can see is that diagnostic items use symbols and lang items use struct fields, is that it?

[camelid]

nikomatsakis when should someone create a lang item instead of using a rustc_diagnostic_item? The only difference I can see is that diagnostic items use symbols and lang items use struct fields, is that it?

I don't know, but just guessing, I would say that the compiler may give special behavior for a lang item (e.g., for add or sized), whereas a diagnostic item is just used to give better error messages.

Also, lang items can be used by the standard library or by user libraries, whereas rustc_diagnostic_item is an internal attribute that is not intended for use outside of the standard library:

error[E0658]: diagnostic items compiler internal support for linting
 --> src/lib.rs:1:1
  |
1 | #[rustc_diagnostic_item = "foo"] fn foo() {}
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

error: aborting due to previous error

[camelid]

I suggested that just to make it clear that language items can be defined outside of the standard library, and that these source locations are specifically the ones defined by the standard library.

[roxelo]

@nikomatsakis Yes, this would have been useful. The only other thing that I think could have helped would have been a basic example of how to add a new lang item, but at the same time that didn't take me too long to figure out with a quick grep.

[jyn514]

I won't have time to follow up on this for at least a month. If @camelid or someone wants to work on this I'm happy for them to do so :)

[rylev]

@jyn514 @camelid this seems pretty good for now even if not 100% complete. Considering it's been sitting for a while, shall we merge it, and just make a quick issue(s) with remaining todos?

[camelid]

this seems pretty good for now even if not 100% complete. Considering it's been sitting for a while, shall we merge it, and just make a quick issue(s) with remaining todos?

That seems good to me!

[jyn514]

Somewhere I had written up a partial answer to Niko's questions, but I seem to have lost it ... anyway, if you're happy with how it is now, could you approve it so I can merge?

[rylev]

🎉