Explain why Task does not impl Eq + Hash.

[carllerche]

Attempt to clarify the problem with using a set structure to store tasks.

This question has come up a bunch; e.g. #670.

[alexcrichton]

Hm the API docs seem like it's not quite the right location for something like this (an FAQ), maybe something like the website and/or somewhere on this repo?

[carllerche]

I mean, the API docs is where people are going to come by here and see it. If you want to move the snippet to a different location, feel free to do so. I just see this question coming up repeatedly so I am trying to address the confusion.

[seanmonstar]

Instead of putting this in the documentation, I'd just leave this as comments in the code, so anyone showing to try adding it can see why. (To clarify, as // instead of /// comments.)

[alexcrichton]

sounds reasonable to me!

[burdges]

I can't comment specifically on where to draw the line in the current situation, but I like it when API docs give a bit more insight into the design and correct usage, like say https://docs.rs/curve25519-dalek/0.14.0/curve25519_dalek/ristretto/index.html

[ahmedcharles]

This is effectively a documenting rationale. There's precedence for having documentation with rationale (all Boost libraries are required to document rationale for important design decisions... there's even a "rationale rationale"): http://www.boost.org/development/requirements.html#Rationale

I.e. add it and your users will thank you later (though, change FAQ to Rationale).

[aturon]

@carllerche want to update this to attach it to Waker?

[carllerche]

@aturon Update it how? afaik, the PR was not accepted?

[carllerche]

Continued here: #1236