From 3f61784be913318c7e4dba56035437c39dec8a27 Mon Sep 17 00:00:00 2001
From: Friedel Ziegelmayer <dignifiedquire@gmail.com>
Date: Thu, 8 Dec 2016 12:27:08 +0100
Subject: [PATCH] docs(api): first pass

---
 .npmignore      |  3 ++-
 src/index.js    | 25 +++++++++++++++++++++++++
 src/listener.js | 42 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 69 insertions(+), 1 deletion(-)

diff --git a/.npmignore b/.npmignore
index 59a480e..94581de 100644
--- a/.npmignore
+++ b/.npmignore
@@ -26,4 +26,5 @@ build/Release
 # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git
 node_modules
 
-test
\ No newline at end of file
+test
+docs
\ No newline at end of file
diff --git a/src/index.js b/src/index.js
index b04c223..cd05ff2 100644
--- a/src/index.js
+++ b/src/index.js
@@ -15,7 +15,18 @@ const createListener = require('./listener')
 
 function noop () {}
 
+/**
+ *
+ */
 class TCP {
+  /**
+   * Dial to another peer.
+   *
+   * @param {Multiaddr} ma - The address of the peer we want to dial to.
+   * @param {Object} [options={}]
+   * @param {function(Error?, Array<Multiaddr>?)} [callback]
+   * @returns {Connection}
+   */
   dial (ma, options, callback) {
     if (isFunction(options)) {
       callback = options
@@ -52,6 +63,13 @@ class TCP {
     return conn
   }
 
+  /**
+   * Listen for incoming `TCP` connetions.
+   *
+   * @param {Object} [options={}]
+   * @param {function(Connection)} [handler] - Called with newly incomin connections.
+   * @returns {Listener}
+   */
   createListener (options, handler) {
     if (isFunction(options)) {
       handler = options
@@ -63,6 +81,13 @@ class TCP {
     return createListener(handler)
   }
 
+  /**
+   * Filter a list of multiaddrs for those which contain
+   * valid `TCP` addresses.
+   *
+   * @param {Multiaddr|Array<Multiaddr>} multiaddrs
+   * @returns {Array<Multiaddr>}
+   */
   filter (multiaddrs) {
     if (!Array.isArray(multiaddrs)) {
       multiaddrs = [multiaddrs]
diff --git a/src/listener.js b/src/listener.js
index 30b3076..65b67a5 100644
--- a/src/listener.js
+++ b/src/listener.js
@@ -17,7 +17,49 @@ const CLOSE_TIMEOUT = 2000
 
 function noop () {}
 
+/**
+ * Listening for incoming connections.
+ *
+ * @event listening
+ * @instance
+ * @memberof Listener
+ */
+
+/**
+ * The server closes.
+ *
+ * @event close
+ * @instance
+ * @memberof Listener
+ */
+
+/**
+ * New connection established.
+ *
+ * @event connection
+ * @instance
+ * @type {Connection}
+ * @memberof Listener
+ */
+
+/**
+ * The underlying server encountered an error.
+ *
+ * @event error
+ * @instance
+ * @type {Error}
+ * @memberof Listener
+ */
+
 module.exports = (handler) => {
+  /**
+   * @alias Listener
+   * @type {Eventemitter}
+   * @fires Listener#listening
+   * @fires Listener#close
+   * @fires Listener#connection
+   * @fires Listener#error
+   */
   const listener = new EventEmitter()
 
   const server = net.createServer((socket) => {