From eb60063e8163ca642edd2dddb7b15a3c252ea310 Mon Sep 17 00:00:00 2001
From: Omidiora Samuel <8148384+samparsky@users.noreply.github.com>
Date: Mon, 26 Aug 2019 13:11:24 +0100
Subject: [PATCH] add: generate typings, jsdoc annotations

---
 .jsdoc.json          | 12 ++++++++++
 .travis.yml          |  1 +
 package.json         |  8 +++++--
 src/get-multiaddr.js | 13 +++++++++--
 src/index.js         | 25 ++++++++++++++++++++-
 src/listener.js      | 12 +++++++++-
 src/types.d.ts       | 53 ++++++++++++++++++++++++++++++++++++++++++++
 7 files changed, 118 insertions(+), 6 deletions(-)
 create mode 100644 .jsdoc.json
 create mode 100644 src/types.d.ts

diff --git a/.jsdoc.json b/.jsdoc.json
new file mode 100644
index 0000000..c40cf3b
--- /dev/null
+++ b/.jsdoc.json
@@ -0,0 +1,12 @@
+{
+    "recurseDepth": 10,
+    "source": {
+        "include": ["src/"],
+        "exclude": ["node_modules"]
+    },
+    "opts": {
+        "destination": "src/",
+        "template": "./node_modules/tsd-jsdoc/dist",
+        "recurse": true
+    }
+}
\ No newline at end of file
diff --git a/.travis.yml b/.travis.yml
index e8d642b..ea298a8 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -30,6 +30,7 @@ jobs:
         - npx aegir commitlint --travis
         - npx aegir dep-check
         - npm run lint
+        - npm run generate-typings
 
 notifications:
   email: false
diff --git a/package.json b/package.json
index ddc480e..3cd3a44 100644
--- a/package.json
+++ b/package.json
@@ -12,7 +12,8 @@
     "release-minor": "aegir release -t node --type minor --no-build",
     "release-major": "aegir-release -t node --type major --no-build",
     "coverage": "aegir coverage",
-    "coverage-publish": "aegir coverage --provider coveralls"
+    "coverage-publish": "aegir coverage --provider coveralls",
+    "generate-typings": "./node_modules/.bin/jsdoc -c ./.jsdoc.json"
   },
   "pre-push": [
     "lint",
@@ -39,7 +40,10 @@
     "chai": "^4.2.0",
     "dirty-chai": "^2.0.1",
     "interface-transport": "~0.3.6",
-    "pull-stream": "^3.6.14"
+    "jsdoc": "^3.6.3",
+    "pull-stream": "^3.6.14",
+    "tsd-jsdoc": "^2.3.1",
+    "typescript-definition-tester": "0.0.6"
   },
   "dependencies": {
     "class-is": "^1.1.0",
diff --git a/src/get-multiaddr.js b/src/get-multiaddr.js
index 4be7243..8a3b4df 100644
--- a/src/get-multiaddr.js
+++ b/src/get-multiaddr.js
@@ -1,11 +1,18 @@
 'use strict'
-
+/**
+ * @module js-libp2p-tcp/get-multiaddr
+ */
 const multiaddr = require('multiaddr')
 const Address6 = require('ip-address').Address6
 const debug = require('debug')
 const log = debug('libp2p:tcp:get-multiaddr')
 
-module.exports = (socket) => {
+/**
+ * @type {function}
+ * @param {*} socket
+ * @returns {*}
+ */
+function getMultiAddr (socket) {
   let ma
 
   try {
@@ -31,3 +38,5 @@ module.exports = (socket) => {
   }
   return ma
 }
+
+module.exports = getMultiAddr
diff --git a/src/index.js b/src/index.js
index b04c223..2ab4a66 100644
--- a/src/index.js
+++ b/src/index.js
@@ -1,5 +1,7 @@
 'use strict'
-
+/**
+ * @module js-libp2p-tcp
+ */
 const net = require('net')
 const toPull = require('stream-to-pull-stream')
 const mafmt = require('mafmt')
@@ -15,7 +17,17 @@ const createListener = require('./listener')
 
 function noop () {}
 
+/**
+ * @class
+ */
 class TCP {
+  /**
+   *
+   * @param {*} ma
+   * @param {object} options
+   * @param {function} callback
+   * @returns {*}
+   */
   dial (ma, options, callback) {
     if (isFunction(options)) {
       callback = options
@@ -52,6 +64,12 @@ class TCP {
     return conn
   }
 
+  /**
+   *
+   * @param {object} options
+   * @param {function} handler
+   * @returns {*}
+   */
   createListener (options, handler) {
     if (isFunction(options)) {
       handler = options
@@ -63,6 +81,11 @@ class TCP {
     return createListener(handler)
   }
 
+  /**
+   *
+   * @param {Array<*>|*} multiaddrs
+   * @returns {*}
+   */
   filter (multiaddrs) {
     if (!Array.isArray(multiaddrs)) {
       multiaddrs = [multiaddrs]
diff --git a/src/listener.js b/src/listener.js
index 30b3076..b92ef2c 100644
--- a/src/listener.js
+++ b/src/listener.js
@@ -1,4 +1,7 @@
 'use strict'
+/**
+ * @module js-libp2p-tcp/listener
+ */
 
 const multiaddr = require('multiaddr')
 const Connection = require('interface-connection').Connection
@@ -17,7 +20,12 @@ const CLOSE_TIMEOUT = 2000
 
 function noop () {}
 
-module.exports = (handler) => {
+/**
+ * @type {function}
+ * @param {function} handler
+ * @returns {*}
+ */
+function listener (handler) {
   const listener = new EventEmitter()
 
   const server = net.createServer((socket) => {
@@ -140,6 +148,8 @@ module.exports = (handler) => {
   return listener
 }
 
+module.exports = listener
+
 function getIpfsId (ma) {
   return ma.stringTuples().filter((tuple) => {
     return tuple[0] === IPFS_CODE
diff --git a/src/types.d.ts b/src/types.d.ts
new file mode 100644
index 0000000..c56965a
--- /dev/null
+++ b/src/types.d.ts
@@ -0,0 +1,53 @@
+/**
+ * @module js-libp2p-tcp/get-multiaddr
+ */
+declare module "js-libp2p-tcp/get-multiaddr" {
+    /**
+     * @type {function}
+     * @param {*} socket
+     * @returns {*}
+     */
+    function getMultiAddr(socket: any): any;
+}
+
+/**
+ * @module js-libp2p-tcp
+ */
+declare module "js-libp2p-tcp" {
+    /**
+     * @class
+     */
+    class TCP {
+        /**
+         *
+         * @param {*} ma
+         * @param {object} options
+         * @param {function} callback
+         */
+        dial(ma: any, options: any, callback: (...params: any[]) => any): void;
+        /**
+         *
+         * @param {object} options
+         * @param {function} handler
+         */
+        createListener(options: any, handler: (...params: any[]) => any): void;
+        /**
+         *
+         * @param {Array<*>|*} multiaddrs
+         */
+        filter(multiaddrs: any[] | any): void;
+    }
+}
+
+/**
+ * @module js-libp2p-tcp/listener
+ */
+declare module "js-libp2p-tcp/listener" {
+    /**
+     * @type {function}
+     * @param {function} handler
+     * @returns {*}
+     */
+    function listener(handler: (...params: any[]) => any): any;
+}
+