warnings should provide guidance (e.g. a url or search term) for where one can learn more

[pnkfelix]

Looking at the self-wake warning, I wondered to myself "how would I know, as someone learning about async rust, why this is a symptom of a problem?"

I'm not even sure I can explain it to someone else. My current thinking goes along the lines of "you're supposed to use async code for stuff where you spend your time waiting for something else to happen. If you're waking yourself up, then that's a sign that you aren't waiting on some other resource." -- to which I can imagine the response "okay. why is that bad?"

Anyway, I don't want this issue to turn into a debate about whether self-wake should be a warning or not (I think its fine that it is). But I do think we need a path for someone who wants to learn more to do self-directed investigation, without having to e.g. join to the Discord and ask for someone there to explain it.

[hawkw]

This is definitely a long-term goal for the warnings system --- I think we've discussed in the past that we should eventually have a searchable, reference-able list of all the warnings the console will emit, like what Clippy has. Ideally, we could automatically generate this documentation from comments in the code that implements the warnings, so that when new warnings are added, it's easy to ensure they're also documented.

I think some of the work involved in #148 would be helpful for this as well, so that we can generate reference-able IDs for each warning, etc.