diff --git a/docs/peer.md b/docs/peer.md
index b931b7e..e089e37 100644
--- a/docs/peer.md
+++ b/docs/peer.md
@@ -1,3 +1,4 @@
+---
 title: Peer
 description: The Peer class provides a simple interface for connecting to a node in the bitcoin network.
 ---
@@ -15,15 +16,15 @@ The code to create a new peer looks like this:
 var Peer = require('bitcore-p2p').Peer;
 
 // default port
-var livenetPeer = new Peer('5.9.85.34');
-var testnetPeer = new Peer('5.9.85.34', bitcore.testnet);
+var livenetPeer = new Peer({host: '5.9.85.34'});
+var testnetPeer = new Peer({host: '5.9.85.34', network: Networks.testnet});
 
 // custom port
-var livenetPeer = new Peer('5.9.85.34', 8334);
-var testnetPeer = new Peer('5.9.85.34', 18334, bitcore.testnet);
+var livenetPeer = new Peer({host: '5.9.85.34', port: 8334});
+var testnetPeer = new Peer({host: '5.9.85.34', port: 18334, network: Networks.testnet});
 
 // use sock5 proxy (Tor)
-var peer = new Peer('5.9.85.34').setProxy('localhost', 9050);
+var peer = new Peer({host: '5.9.85.34'}).setProxy('localhost', 9050);
 ```
 
 ## States
@@ -40,7 +41,7 @@ You can subscribe to the change of those states as follows:
 ```javascript
 var Peer = require('bitcore-p2p').Peer;
 
-var peer = new Peer('5.9.85.34');
+var peer = new Peer({host: '5.9.85.34'});
 
 peer.on('ready', function() {
   // peer info
@@ -60,7 +61,7 @@ Once connected, a peer instance can send and receive messages. Every time a mess
 
 ```javascript
 var Peer = require('bitcore-p2p').Peer;
-var peer = new Peer('5.9.85.34');
+var peer = new Peer({host: '5.9.85.34'});
 
 // handle events
 peer.on('inv', function(message) {
@@ -88,7 +89,7 @@ An example for requesting other connected nodes to a peers looks like this:
 var p2p = require('bitcore-p2p')
 var Peer = p2p.Peer;
 var Messages = p2p.Messages;
-var peer = new Peer('5.9.85.34');
+var peer = new Peer({host: '5.9.85.34'});
 
 peer.on('ready', function() {
   var message = new Messages.GetAddresses();
diff --git a/docs/pool.md b/docs/pool.md
index e09aae0..fbffb82 100644
--- a/docs/pool.md
+++ b/docs/pool.md
@@ -1,3 +1,4 @@
+---
 title: Pool
 description: A simple interface to create and maintain a set of connections to bitcoin nodes.
 ---
@@ -12,7 +13,7 @@ The quickest way to get connected is to run the following:
 var Pool = require('bitcore-p2p').Pool;
 var Networks = require('bitcore').Networks;
 
-var pool = new Pool(Networks.livenet);
+var pool = new Pool({network: Networks.livenet});
 
 // connect to the network
 pool.connect();
@@ -35,7 +36,8 @@ By default, peers will be added via DNS discovery and as peers are announced in
 
 ```javascript
 
-var pool = new Pool(Networks.livenet, {
+var pool = new Pool({
+  network: Networks.livenet, // the network object
   dnsSeed: false, // prevent seeding with DNS discovered known peers upon connecting
   listenAddr: false, // prevent new peers being added from addr messages
   addrs: [ // initial peers to connect to
@@ -50,3 +52,14 @@ var pool = new Pool(Networks.livenet, {
 pool.connect();
 
 ```
+
+## Listening for Peers
+
+It's also possible to listen to incoming socket connections to add peers to the pool. To enable this capability, you can do the following:
+
+```javascript
+var pool = new Pool({network: Networks.livenet});
+pool.listen();
+```
+
+When there are incoming connections the peer will be added to the pool.
\ No newline at end of file