feat: add example usage (#13)

README.md

@@ -40,12 +40,35 @@
 
 Happy Eyeballs
 
+## Use case
+
+This library exists to allow connecting with Happy Eyeballs when you
+already have a list of addrinfo and not a DNS name.
+
+The stdlib version of `loop.create_connection()`
+will only work when you pass in an unresolved name which
+is not a good fit when using DNS caching or resolving
+names via another method such was `zeroconf`.
+
 ## Installation
 
 Install this via pip (or your favourite package manager):
 
 `pip install aiohappyeyeballs`
 
+## Example usage
+
+```python
+
+addr_infos = await loop.getaddrinfo("example.org", 80)
+
+socket = await start_connection(addr_infos)
+
+transport, protocol = await loop.create_connection(
+    MyProtocol, sock=socket, ...)
+
+```
+
 ## Credits
 
 This package contains code from cpython and is licensed under the same terms as cpython itself.

src/aiohappyeyeballs/impl.py

@@ -46,6 +46,13 @@ async def start_connection(
     This method is a coroutine which will try to establish the connection
     in the background. When successful, the coroutine returns a
     socket.
+
+    The expected use case is to use this method in conjunction with
+    loop.create_connection() to establish a connection to a server::
+
+            socket = await start_connection(addr_infos)
+            transport, protocol = await loop.create_connection(
+                MyProtocol, sock=socket, ...)
     """
     if not (current_loop := loop):
         current_loop = asyncio.get_running_loop()