diff --git a/src/pubsub.js b/src/pubsub.js
index 2ed88ea997..a8b429c923 100644
--- a/src/pubsub.js
+++ b/src/pubsub.js
@@ -13,10 +13,31 @@ module.exports = (node) => {
   node._floodSub = floodSub
 
   return {
-    subscribe: promisify((topic, options, handler, callback) => {
+    /**
+     * Subscribe the given handler to a pubsub topic
+     *
+     * @param {string} topic
+     * @param {function} handler The handler to subscribe
+     * @param {object|null} [options]
+     * @param {function} [callback] An optional callback
+     *
+     * @returns {Promise|void} A promise is returned if no callback is provided
+     *
+     * @example <caption>Subscribe a handler to a topic</caption>
+     *
+     * // `null` must be passed for options until subscribe is no longer using promisify
+     * const handler = (message) => { }
+     * await libp2p.subscribe(topic, handler, null)
+     *
+     * @example <caption>Use a callback instead of the Promise api</caption>
+     *
+     * // `options` may be passed or omitted when supplying a callback
+     * const handler = (message) => { }
+     * libp2p.subscribe(topic, handler, callback)
+     */
+    subscribe: promisify((topic, handler, options, callback) => {
       if (typeof options === 'function') {
-        callback = handler
-        handler = options
+        callback = options
         options = {}
       }
 
diff --git a/test/pubsub.node.js b/test/pubsub.node.js
index ca1f1071b4..b45e577cc6 100644
--- a/test/pubsub.node.js
+++ b/test/pubsub.node.js
@@ -72,7 +72,7 @@ describe('.pubsub', () => {
           cb(err)
         }),
         // subscribe on the first
-        (cb) => nodes[0].pubsub.subscribe('pubsub', handler, cb),
+        (cb) => nodes[0].pubsub.subscribe('pubsub', handler, null, cb),
         // Wait a moment before publishing
         (cb) => setTimeout(cb, 500),
         // publish on the second
@@ -110,7 +110,7 @@ describe('.pubsub', () => {
           cb(err)
         }),
         // subscribe on the first
-        (cb) => nodes[0].pubsub.subscribe('pubsub', handler, cb),
+        (cb) => nodes[0].pubsub.subscribe('pubsub', handler, {}, cb),
         // Wait a moment before publishing
         (cb) => setTimeout(cb, 500),
         // publish on the second