Improve README guide & document public API

[njgheorghita]

A lot of the difficulty I'm having with this library is that it's difficult to understand how to use it. The example in the README is somewhat pseudocode. It doesn't compile, and uses types that are not valid according to the compiler (eg. CustomSocket / let remote = SocketAddr::from(..); / what is udp_socket?). This makes it a challenging resource to rely upon while debugging.

A lot of this knowledge resides in @jacobkaufmann 's head and it would be useful if you could improve the documentation to explicitly & correctly show the public api for this library.

I understand that the README example contains enough context that I should be able to interpret the public api, but explicit, correct examples are extremely helpful as a reference. Simple examples for a utp tx using both connect() and connect_with_cid() would be very helpful.

As an aside... I'm also curious as to why there are both connect() & connect_with_cid() api's available? What are the use cases for each method? Is using one preferable to the other?

[jacobkaufmann]

I agree that the documentation needs improvement. I will take this up to create some more examples in the method doc comments.

with connect the connection ID (CID) is generated "under the hood", so it would be used if you did not need to pre-negotiate a CID. I can add some more details to the doc comments there.

[emhane]

Would you mind to edit the name of this issue so it includes "document public API"? @njgheorghita