Generate Typescript Typings via JsDoc

.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
+    }
+}

.travis.yml

@@ -23,6 +23,7 @@ jobs:
         - npx aegir build --bundlesize
         - npx aegir dep-check -- -i wrtc -i electron-webrtc
         - npm run lint
+        - npm run generate-typings
 
     - stage: test
       name: chrome

package.json

@@ -4,6 +4,7 @@
   "description": "JavaScript implementation of libp2p, a modular peer to peer network stack",
   "leadMaintainer": "Jacob Heun <[email protected]>",
   "main": "src/index.js",
+  "typings": "src/types.d.ts",
   "files": [
     "dist",
     "src"
@@ -17,7 +18,8 @@
     "release": "aegir release -t node -t browser",
     "release-minor": "aegir release --type minor -t node -t browser",
     "release-major": "aegir release --type major -t node -t browser",
-    "coverage": "nyc --reporter=text --reporter=lcov npm run test:node"
+    "coverage": "nyc --reporter=text --reporter=lcov npm run test:node",
+    "generate-typings": "./node_modules/.bin/jsdoc -c ./.jsdoc.json"
   },
   "repository": {
     "type": "git",
@@ -84,6 +86,7 @@
     "dirty-chai": "^2.0.1",
     "electron-webrtc": "^0.3.0",
     "interface-datastore": "^0.6.0",
+    "jsdoc": "^3.6.3",
     "libp2p-bootstrap": "^0.9.7",
     "libp2p-delegated-content-routing": "^0.2.2",
     "libp2p-delegated-peer-routing": "^0.2.2",
@@ -109,6 +112,7 @@
     "pull-protocol-buffers": "~0.1.2",
     "pull-serializer": "^0.3.2",
     "sinon": "^7.2.7",
+    "tsd-jsdoc": "^2.3.1",
     "wrtc": "^0.4.1"
   },
   "contributors": [

src/circuit/circuit.js

@@ -12,6 +12,7 @@ log.err = debug('libp2p:circuit:error:transportdialer')
 
 const createListener = require('./listener')
 
+/** @class Circuit */
 class Circuit {
   static get tag () {
     return 'Circuit'

src/circuit/circuit/dialer.js

@@ -18,13 +18,16 @@ log.err = debug('libp2p:circuit:error:dialer')
 const multicodec = require('../multicodec')
 const proto = require('../protocol')
 
+/**
+ * @class Dialer
+ * 
+ */
 class Dialer {
   /**
    * Creates an instance of Dialer.
    * @param {Swarm} swarm - the swarm
    * @param {any} options - config options
    *
-   * @memberOf Dialer
    */
   constructor (swarm, options) {
     this.swarm = swarm

src/circuit/circuit/stop.js

@@ -14,6 +14,10 @@ const debug = require('debug')
 const log = debug('libp2p:circuit:stop')
 log.err = debug('libp2p:circuit:error:stop')
 
+/**
+ * @class
+ * @extends EventEmitter
+ */
 class Stop extends EE {
   constructor (swarm) {
     super()

src/circuit/circuit/utils.js

@@ -6,7 +6,11 @@ const PeerId = require('peer-id')
 const proto = require('../protocol')
 const { getPeerInfo } = require('../../get-peer-info')
 
-module.exports = function (swarm) {
+/**
+ * Utils
+ * 
+ */
+function utils (swarm) {
   /**
    * Get b58 string from multiaddr or peerinfo
    *
@@ -116,3 +120,5 @@ module.exports = function (swarm) {
     peerIdFromId
   }
 }
+
+module.exports = utils

src/circuit/listener.js

@@ -17,8 +17,18 @@ const debug = require('debug')
 
 const log = debug('libp2p:circuit:listener')
 log.err = debug('libp2p:circuit:error:listener')
-
-module.exports = (swarm, options, connHandler) => {
+/**
+ * @method
+ * 
+ * @param {@} swarm 
+ * @param {*} options 
+ * @param {*} connHandler 
+ * @returns {EventEmitter}
+ */
+function listener (swarm, options, connHandler) {
+  /**
+   * @class
+   */
   const listener = new EE()
   const utils = utilsFactory(swarm)
 
@@ -28,7 +38,7 @@ module.exports = (swarm, options, connHandler) => {
 
   /**
    * Add swarm handler and listen for incoming connections
-   *
+   * 
    * @param {Multiaddr} ma
    * @param {Function} callback
    * @return {void}
@@ -147,3 +157,5 @@ module.exports = (swarm, options, connHandler) => {
 
   return listener
 }
+
+module.exports = listener

src/content-routing.js

@@ -5,7 +5,12 @@ const parallel = require('async/parallel')
 const errCode = require('err-code')
 const promisify = require('promisify-es6')
 
-module.exports = (node) => {
+/**
+ * @method
+ * @param {*} node 
+ */
+
+function router(node) {
   const routers = node._modules.contentRouting || []
 
   // If we have the dht, make it first
@@ -17,13 +22,14 @@ module.exports = (node) => {
     /**
      * Iterates over all content routers in series to find providers of the given key.
      * Once a content router succeeds, iteration will stop.
-     *
+     * 
+     * @method
      * @param {CID} key The CID key of the content to find
      * @param {object} options
      * @param {number} options.maxTimeout How long the query should run
      * @param {number} options.maxNumProviders - maximum number of providers to find
      * @param {function(Error, Result<Array>)} callback
-     * @returns {void}
+     * @promise {void}
      */
     findProviders: promisify((key, options, callback) => {
       if (typeof options === 'function') {
@@ -67,6 +73,7 @@ module.exports = (node) => {
      * Iterates over all content routers in parallel to notify it is
      * a provider of the given key.
      *
+     * @method
      * @param {CID} key The CID key of the content to find
      * @param {function(Error)} callback
      * @returns {void}
@@ -82,3 +89,5 @@ module.exports = (node) => {
     })
   }
 }
+
+module.exports = router

src/index.js

@@ -567,9 +567,11 @@ module.exports = Libp2p
 /**
  * Like `new Libp2p(options)` except it will create a `PeerInfo`
  * instance if one is not provided in options.
+ * 
+ * @method
  * @param {object} options Libp2p configuration options
  * @param {function(Error, Libp2p)} callback
- * @returns {void}
+ * @return {Promise<{void}>}
  */
 module.exports.createLibp2p = promisify((options, callback) => {
   if (options.peerInfo) {

src/peer-routing.js

@@ -16,6 +16,7 @@ module.exports = (node) => {
     /**
      * Iterates over all peer routers in series to find the given peer.
      *
+     * @method
      * @param {String} id The id of the peer to find
      * @param {object} options
      * @param {number} options.maxTimeout How long the query should run

src/pubsub.js

@@ -13,6 +13,7 @@ module.exports = (node, Pubsub, config) => {
     /**
      * Subscribe the given handler to a pubsub topic
      *
+     * @method
      * @param {string} topic
      * @param {function} handler The handler to subscribe
      * @param {object|null} [options]
@@ -57,6 +58,7 @@ module.exports = (node, Pubsub, config) => {
     /**
      * Unsubscribes from a pubsub topic
      *
+     * @method
      * @param {string} topic
      * @param {function|null} handler The handler to unsubscribe from
      * @param {function} [callback] An optional callback

src/switch/connection/base.js

@@ -4,6 +4,7 @@ const EventEmitter = require('events').EventEmitter
 const debug = require('debug')
 const withIs = require('class-is')
 
+/** @class BaseConnection */
 class BaseConnection extends EventEmitter {
   constructor ({ _switch, name }) {
     super()

src/switch/dialer/index.js

@@ -11,6 +11,9 @@ const {
   PRIORITY_LOW
 } = require('../constants')
 
+/**
+ * @module dialer/index
+ */
 module.exports = function (_switch) {
   const dialQueueManager = new DialQueueManager(_switch)
 

src/switch/dialer/queue.js

@@ -16,7 +16,7 @@ log.error = debug('libp2p:switch:dial:error')
  * @property {object} options
  * @property {boolean} options.useFSM - If `callback` should return a ConnectionFSM
  * @property {number} options.priority - The priority of the dial
- * @property {function(Error, Connection|ConnectionFSM)} callback
+ * @property {function} callback function(Error, Connection|ConnectionFSM)
  */
 
 /**

src/switch/observer.js

@@ -12,7 +12,7 @@ const EventEmitter = require('events')
  * @param {Switch} swtch
  * @returns {EventEmitter}
  */
-module.exports = (swtch) => {
+function observer (swtch) {
   const observer = Object.assign(new EventEmitter(), {
     incoming: observe('in'),
     outgoing: observe('out')
@@ -46,3 +46,4 @@ module.exports = (swtch) => {
     })
   }
 }
+module.exports = observer

src/switch/stats/index.js

@@ -35,7 +35,7 @@ const directionToEvent = {
  * @param {any} _options
  * @returns {Stats}
  */
-module.exports = (observer, _options) => {
+function stats (observer, _options) {
   const options = Object.assign({}, defaultOptions, _options)
   const globalStats = new Stat(initialCounters, options)
 
@@ -148,3 +148,5 @@ module.exports = (observer, _options) => {
     stats.emit('update')
   }
 }
+
+module.exports = stats

src/switch/stats/old-peers.js

@@ -8,8 +8,9 @@ const LRU = require('hashlru')
  * @param {Number} maxSize
  * @returns {LRUCache}
  */
-module.exports = (maxSize) => {
+function oldPeers (maxSize) {
   const patched = LRU(maxSize)
   patched.delete = patched.remove
   return patched
 }
+module.exports = oldPeers

src/switch/stats/stat.js

@@ -67,7 +67,9 @@ class Stats extends EventEmitter {
 
   /**
    * Returns a clone of the current stats.
-   *
+   * 
+   * @method
+   * @readonly
    * @returns {Map<string, Stat>}
    */
   get snapshot () {
@@ -76,7 +78,9 @@ class Stats extends EventEmitter {
 
   /**
    * Returns a clone of the internal movingAverages
-   *
+   * 
+   * @method
+   * @readonly
    * @returns {Array<MovingAverage>}
    */
   get movingAverages () {