Documentation: what's a "peer" object, what does "holepunch" do

Hello, some friendly feedback about improving the docs for this module <3

What's the scope of this module?

It gives you the ip addresses of peers and holepunches to them? Meaning you get a stream to each peer?

What's a peer object?

Docs say

// emitted when a peer is found
lookup.on('peer', console.log)

...but what's in a peer object? What can it do?

I think this is the answer? https://github.com/hyperswarm/discovery/blob/master/index.js#L389

        topic.emit('peer', { port: a.data.port, host, local: true, referrer: null, topic: topic.key })

So a peer is mostly a port and hostname, not a stream.

What does `holepunch` do?

Docs just say:

d.holepunch(peer, cb) UDP holepunch to another peer.

What actually happens? What does the callback get?

Looking in the code, it just calls dht.holepunch. The docs for hyperswarm/dht just say

node.holepunch(peer, [callback])

UDP holepunch to another peer.

peer should be a { host, port, referrer: { host, port } }, where referrer should be the host and port of the DHT node who told you about this peer.

Ok, so that's probably the peer object we were talking about earlier. But what does this do, and what's provided to the callback?

The word holepunch does not occur in any of the code in hyperswarm/dht so I can't find what it's actually doing.

hyperswarm / discovery