add documentation to the span_lint_hir functions

[y21]

As far as I could tell, these weren't documented anywhere, and since this is sometimes needed over span_lint for #[allow] attrs to work, I thought I would add a little bit of documentation.
When I started with clippy development, I also had no idea what these functions were for.

changelog: none

[rustbot]

r? @Manishearth

rustbot has assigned @Manishearth.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[xFrednet]

It's good to see these functions getting some love!

I have a few suggestions, but either way, this is a really awesome change!

r? @xFrednet

[xFrednet]

I hope my comments are not too nit-picky :D

[y21]

Changed the documentation a bit with (a lot of) inspiration taken from the suggestions

I hope my comments are not too nit-picky :D

It's fine, especially for a PR like this. These functions are used everywhere, so imo having good documentation here is important. So feel free to point out things that you would phrase differently, even small details.

[xFrednet]

Perfect, I like this version! This is a really nice improvement :D

@bors r+

[bors]

📌 Commit 5b1f95c has been approved by xFrednet

It is now in the queue for this repository.

[bors]

⌛ Testing commit 5b1f95c with merge 86717f2...

[bors]

☀️ Test successful - checks-action_dev_test, checks-action_remark_test, checks-action_test
Approved by: xFrednet
Pushing 86717f2 to master...