f clean up discussion of file-descriptor use and recommend not doing it

Author: TheBlueMatt

lightning/src/ln/peer_handler.rs

@@ -178,16 +178,12 @@ pub struct MessageHandler<CM: Deref, RM: Deref> where
 ///
 /// For efficiency, Clone should be relatively cheap for this type.
 ///
-/// If applicable in your language, you probably want to just extend an int and put a file
-/// descriptor in a struct and implement this trait on it. Note, of course, that if you do so and
-/// have multiple threads interacting with the [`PeerManager`], you must not call `close()` on the
-/// file descriptor until all threads are guaranteed to not call any [`PeerManager`] functions with
-/// the same descriptor. Otherwise, file descriptor re-use could imply that you call a
-/// [`PeerManager`] function with a file descriptor representing a different connection.
-///
-/// Note that if you are using a higher-level net library that may call close() itself when you
-/// close a socket, be careful to ensure you don't directly use the file descriptor for your [`Eq`]
-/// and [`Hash`] implementations.
+/// Two descriptors may compare equal (by [`cmp::Eq`] and [`hash::Hash`]) as long as the original
+/// has been disconnected, the [`PeerManager`] informed of the disconnection (either by it having
+/// triggered the disconnection or a call to [`PeerManager::socket_disconnected`]), and no further
+/// calls to the [`PeerManager`] related to the original socket occur. This allows you to use a
+/// file descriptor for your SocketDescriptor directly, however for simplicity you may wish to
+/// simply use another value which is guaranteed to be globally unique instead.
 pub trait SocketDescriptor : cmp::Eq + hash::Hash + Clone {
 	/// Attempts to send some data from the given slice to the peer.
 	///