From c471c9d461ad101c47d5e41397d79a2f0b8cab4a Mon Sep 17 00:00:00 2001 From: Omidiora Samuel <> Date: Mon, 26 Aug 2019 10:58:42 +0100 Subject: [PATCH 1/3] add: jsdoc configuration --- .jsdoc.json | 12 ++++++++++++ package.json | 8 ++++++-- 2 files changed, 18 insertions(+), 2 deletions(-) create mode 100644 .jsdoc.json 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/package.json b/package.json index 74b3523..a2d5fa1 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,8 @@ "release": "aegir release -t node --no-build", "release-minor": "aegir release --type minor -t node --no-build", "release-major": "aegir release --type major -t node --no-build", - "coverage-publish": "aegir coverage publish" + "coverage-publish": "aegir coverage publish", + "generate-typings": "./node_modules/.bin/jsdoc -c ./.jsdoc.json" }, "pre-push": [ "lint" @@ -36,7 +37,10 @@ "devDependencies": { "aegir": "^18.2.2", "chai": "^4.2.0", - "dirty-chai": "^2.0.1" + "dirty-chai": "^2.0.1", + "jsdoc": "^3.6.3", + "tsd-jsdoc": "^2.3.1", + "typescript-definition-tester": "0.0.6" }, "dependencies": { "async": "^2.6.2", From 915bb1f9102f4264eb3ea861de19f49852a80b9d Mon Sep 17 00:00:00 2001 From: Omidiora Samuel <> Date: Mon, 26 Aug 2019 11:07:16 +0100 Subject: [PATCH 2/3] add: jsdoc documentation --- .travis.yml | 1 + src/compat/index.js | 22 ++++++++-- src/compat/querier.js | 22 +++++++++- src/compat/responder.js | 7 +++ src/index.js | 22 ++++++++-- src/types.d.ts | 95 +++++++++++++++++++++++++++++++++++++++++ 6 files changed, 162 insertions(+), 7 deletions(-) create mode 100644 src/types.d.ts diff --git a/.travis.yml b/.travis.yml index 7cf83ca..94b2c8d 100644 --- a/.travis.yml +++ b/.travis.yml @@ -25,6 +25,7 @@ jobs: - npx aegir commitlint --travis - npx aegir dep-check - npm run lint + - npm run generate-typings notifications: email: false \ No newline at end of file diff --git a/src/compat/index.js b/src/compat/index.js index 495f3cb..d75cf33 100644 --- a/src/compat/index.js +++ b/src/compat/index.js @@ -7,14 +7,24 @@ const parallel = require('async/parallel') const Responder = require('./responder') const Querier = require('./querier') +/** + * @class + */ class GoMulticastDNS extends EE { + /** + * + * @param {object} peerInfo + */ constructor (peerInfo) { super() this._started = false this._peerInfo = peerInfo this._onPeer = this._onPeer.bind(this) } - + /** + * + * @param {function} callback + */ start (callback) { if (this._started) { return callback(new Error('MulticastDNS service is already started')) @@ -31,11 +41,17 @@ class GoMulticastDNS extends EE { cb => this._querier.start(cb) ], callback) } - + /** + * + * @param {object} peerInfo + */ _onPeer (peerInfo) { this.emit('peer', peerInfo) } - + /** + * + * @param {function} callback + */ stop (callback) { if (!this._started) { return callback(new Error('MulticastDNS service is not started')) diff --git a/src/compat/querier.js b/src/compat/querier.js index eaa9878..389398b 100644 --- a/src/compat/querier.js +++ b/src/compat/querier.js @@ -10,7 +10,15 @@ const nextTick = require('async/nextTick') const log = require('debug')('libp2p:mdns:compat:querier') const { SERVICE_TAG_LOCAL, MULTICAST_IP, MULTICAST_PORT } = require('./constants') +/** + * @class + */ class Querier extends EE { + /** + * + * @param {object} peerId + * @param {object} options + */ constructor (peerId, options) { super() assert(peerId, 'missing peerId parameter') @@ -28,6 +36,10 @@ class Querier extends EE { this._onResponse = this._onResponse.bind(this) } + /** + * + * @param {function} callback + */ start (callback) { this._handle = periodically(() => { // Create a querier that queries multicast but gets responses unicast @@ -57,6 +69,11 @@ class Querier extends EE { nextTick(() => callback()) } + /** + * + * @param {object} event + * @param {object} info + */ _onResponse (event, info) { const answers = event.answers || [] const ptrRecord = answers.find(a => a.type === 'PTR' && a.name === SERVICE_TAG_LOCAL) @@ -115,7 +132,10 @@ class Querier extends EE { this.emit('peer', info) }) } - + /** + * + * @param {function} callback + */ stop (callback) { this._handle.stop(callback) } diff --git a/src/compat/responder.js b/src/compat/responder.js index da3ec4c..cba226b 100644 --- a/src/compat/responder.js +++ b/src/compat/responder.js @@ -10,7 +10,14 @@ const { SERVICE_TAG_LOCAL } = require('./constants') const tcp = new TCP() +/** + * @class + */ class Responder { + /** + * + * @param {object} peerInfo + */ constructor (peerInfo) { assert(peerInfo, 'missing peerInfo parameter') this._peerInfo = peerInfo diff --git a/src/index.js b/src/index.js index f2c3657..9a1c3ae 100644 --- a/src/index.js +++ b/src/index.js @@ -10,7 +10,14 @@ const log = debug('libp2p:mdns') const query = require('./query') const GoMulticastDNS = require('./compat') +/** + * @class + */ class MulticastDNS extends EventEmitter { + /** + * + * @param {object} options + */ constructor (options) { super() assert(options.peerInfo, 'needs a PeerInfo to work') @@ -31,7 +38,10 @@ class MulticastDNS extends EventEmitter { this._goMdns.on('peer', this._onPeer) } } - + /** + * + * @param {function} callback + */ start (callback) { const mdns = multicastDNS({ port: this.port }) @@ -59,11 +69,17 @@ class MulticastDNS extends EventEmitter { nextTick(() => callback()) } } - + /** + * + * @param {object} peerInfo + */ _onPeer (peerInfo) { this.emit('peer', peerInfo) } - + /** + * + * @param {function} callback + */ stop (callback) { if (!this.mdns) { return callback(new Error('MulticastDNS service had not started yet')) diff --git a/src/types.d.ts b/src/types.d.ts new file mode 100644 index 0000000..c97460e --- /dev/null +++ b/src/types.d.ts @@ -0,0 +1,95 @@ +/** + * + * @param {object} peerInfo + */ +declare class GoMulticastDNS { + constructor(peerInfo: any); + /** + * + * @param {function} callback + */ + start(callback: (...params: any[]) => any): void; + /** + * + * @param {object} peerInfo + */ + _onPeer(peerInfo: any): void; + /** + * + * @param {function} callback + */ + stop(callback: (...params: any[]) => any): void; +} + +/** + * + * @param {object} peerId + * @param {object} options + */ +declare class Querier { + constructor(peerId: any, options: any); + /** + * + * @param {function} callback + */ + start(callback: (...params: any[]) => any): void; + /** + * + * @param {object} event + * @param {object} info + */ + _onResponse(event: any, info: any): void; + /** + * + * @param {function} callback + */ + stop(callback: (...params: any[]) => any): void; +} + +/** + * Run `fn` for a certain period of time, and then wait for an interval before + * running it again. `fn` must return an object with a stop function, which is + * called when the period expires. + * + * @param {Function} fn function to run + * @param {Object} [options] + * @param {Object} [options.period] Period in ms to run the function for + * @param {Object} [options.interval] Interval in ms between runs + * @returns {Object} handle that can be used to stop execution + */ +declare function periodically(fn: (...params: any[]) => any, options?: { + period?: any; + interval?: any; +}): any; + +/** + * + * @param {object} peerInfo + */ +declare class Responder { + constructor(peerInfo: any); +} + +/** + * + * @param {object} options + */ +declare class MulticastDNS { + constructor(options: any); + /** + * + * @param {function} callback + */ + start(callback: (...params: any[]) => any): void; + /** + * + * @param {object} peerInfo + */ + _onPeer(peerInfo: any): void; + /** + * + * @param {function} callback + */ + stop(callback: (...params: any[]) => any): void; +} + From de266540cec0824660dd74b37f07b2c258086a66 Mon Sep 17 00:00:00 2001 From: Omidiora Samuel <> Date: Mon, 26 Aug 2019 11:16:12 +0100 Subject: [PATCH 3/3] fix: linting errors --- src/compat/index.js | 18 ++++++++++-------- src/compat/querier.js | 21 +++++++++++---------- src/compat/responder.js | 4 ++-- src/index.js | 17 +++++++++-------- 4 files changed, 32 insertions(+), 28 deletions(-) diff --git a/src/compat/index.js b/src/compat/index.js index d75cf33..8912a93 100644 --- a/src/compat/index.js +++ b/src/compat/index.js @@ -12,8 +12,8 @@ const Querier = require('./querier') */ class GoMulticastDNS extends EE { /** - * - * @param {object} peerInfo + * + * @param {object} peerInfo */ constructor (peerInfo) { super() @@ -22,8 +22,9 @@ class GoMulticastDNS extends EE { this._onPeer = this._onPeer.bind(this) } /** - * - * @param {function} callback + * + * @param {function} callback + * @returns {functio} */ start (callback) { if (this._started) { @@ -42,15 +43,16 @@ class GoMulticastDNS extends EE { ], callback) } /** - * - * @param {object} peerInfo + * + * @param {object} peerInfo */ _onPeer (peerInfo) { this.emit('peer', peerInfo) } /** - * - * @param {function} callback + * + * @param {function} callback + * @returns {?object} */ stop (callback) { if (!this._started) { diff --git a/src/compat/querier.js b/src/compat/querier.js index 389398b..3eff35b 100644 --- a/src/compat/querier.js +++ b/src/compat/querier.js @@ -15,9 +15,9 @@ const { SERVICE_TAG_LOCAL, MULTICAST_IP, MULTICAST_PORT } = require('./constants */ class Querier extends EE { /** - * - * @param {object} peerId - * @param {object} options + * + * @param {object} peerId + * @param {object} options */ constructor (peerId, options) { super() @@ -37,8 +37,8 @@ class Querier extends EE { } /** - * - * @param {function} callback + * + * @param {function} callback */ start (callback) { this._handle = periodically(() => { @@ -70,9 +70,10 @@ class Querier extends EE { } /** - * - * @param {object} event - * @param {object} info + * + * @param {object} event + * @param {object} info + * @returns {?object} */ _onResponse (event, info) { const answers = event.answers || [] @@ -133,8 +134,8 @@ class Querier extends EE { }) } /** - * - * @param {function} callback + * + * @param {function} callback */ stop (callback) { this._handle.stop(callback) diff --git a/src/compat/responder.js b/src/compat/responder.js index cba226b..a77d237 100644 --- a/src/compat/responder.js +++ b/src/compat/responder.js @@ -15,8 +15,8 @@ const tcp = new TCP() */ class Responder { /** - * - * @param {object} peerInfo + * + * @param {object} peerInfo */ constructor (peerInfo) { assert(peerInfo, 'missing peerInfo parameter') diff --git a/src/index.js b/src/index.js index 9a1c3ae..ae33b4a 100644 --- a/src/index.js +++ b/src/index.js @@ -15,8 +15,8 @@ const GoMulticastDNS = require('./compat') */ class MulticastDNS extends EventEmitter { /** - * - * @param {object} options + * + * @param {object} options */ constructor (options) { super() @@ -39,8 +39,8 @@ class MulticastDNS extends EventEmitter { } } /** - * - * @param {function} callback + * + * @param {function} callback */ start (callback) { const mdns = multicastDNS({ port: this.port }) @@ -70,15 +70,16 @@ class MulticastDNS extends EventEmitter { } } /** - * - * @param {object} peerInfo + * + * @param {object} peerInfo */ _onPeer (peerInfo) { this.emit('peer', peerInfo) } /** - * - * @param {function} callback + * + * @param {function} callback + * @returns {function} */ stop (callback) { if (!this.mdns) {