Merge branches 'master' and 'master' of github.com:ipfs/js-ipfsd-ctl

* 'master' of github.com:ipfs/js-ipfsd-ctl:
  Chore/improve docs (#294)

* 'master' of github.com:ipfs/js-ipfsd-ctl:
  Chore/improve docs (#294)

src/endpoint/routes.js

@@ -17,6 +17,12 @@ const routeConfig = {
 
 let nodes = {}
 
+/**
+ * @namespace EndpointServerRoutes
+ * @ignore
+ * @param {Hapi.Server} server
+ * @returns {void}
+ */
 module.exports = (server) => {
   server.route({
     method: 'GET',
@@ -46,10 +52,10 @@ module.exports = (server) => {
     }
   })
 
-  /**
+  /*
    * Spawn an IPFS node
    * The repo is created in a temporary location and cleaned up on process exit.
-   **/
+   */
   server.route({
     method: 'POST',
     path: '/spawn',
@@ -85,9 +91,9 @@ module.exports = (server) => {
     }
   })
 
-  /**
+  /*
    * Initialize a repo.
-   **/
+   */
   server.route({
     method: 'POST',
     path: '/init',
@@ -107,9 +113,9 @@ module.exports = (server) => {
     config: routeConfig
   })
 
-  /**
+  /*
    * Start the daemon.
-   **/
+   */
   server.route({
     method: 'POST',
     path: '/start',
@@ -135,7 +141,7 @@ module.exports = (server) => {
     config: routeConfig
   })
 
-  /**
+  /*
    * Get the address of connected IPFS API.
    */
   server.route({
@@ -149,8 +155,9 @@ module.exports = (server) => {
     config: routeConfig
   })
 
-  /**
+  /*
    * Get the address of connected IPFS HTTP Gateway.
+   * @memberof EndpointServerRoutes
    */
   server.route({
     method: 'GET',
@@ -162,11 +169,11 @@ module.exports = (server) => {
     config: routeConfig
   })
 
-  /**
+  /*
    * Delete the repo that was being used.
    * If the node was marked as `disposable` this will be called
    * automatically when the process is exited.
-   **/
+   */
   server.route({
     method: 'POST',
     path: '/cleanup',
@@ -183,7 +190,7 @@ module.exports = (server) => {
     config: routeConfig
   })
 
-  /**
+  /*
    * Stop the daemon.
    */
   server.route({
@@ -203,7 +210,7 @@ module.exports = (server) => {
     config: routeConfig
   })
 
-  /**
+  /*
    * Kill the `ipfs daemon` process.
    *
    * First `SIGTERM` is sent, after 7.5 seconds `SIGKILL` is sent
@@ -226,10 +233,8 @@ module.exports = (server) => {
     config: routeConfig
   })
 
-  /**
+  /*
    * Get the pid of the `ipfs daemon` process.
-   *
-   * @returns {number}
    */
   server.route({
     method: 'GET',
@@ -242,7 +247,7 @@ module.exports = (server) => {
     config: routeConfig
   })
 
-  /**
+  /*
    * Call `ipfs config`
    *
    * If no `key` is passed, the whole config is returned as an object.
@@ -270,7 +275,7 @@ module.exports = (server) => {
     }, routeConfig)
   })
 
-  /**
+  /*
    * Set a config value.
    */
   server.route({

src/endpoint/server.js

@@ -3,6 +3,11 @@
 const Hapi = require('hapi')
 const routes = require('./routes')
 
+/**
+ * Creates an instance of Server.
+ * @param {Object} options
+ * @param {number} [options.port=43134] - Server port.
+ */
 class Server {
   constructor (options) {
     options = options || { port: 43134 }
@@ -11,6 +16,12 @@ class Server {
     this.port = options.port
   }
 
+  /**
+   * Start the server
+   *
+   * @param {function(Error, Hapi.Server): void} cb
+   * @returns {void}
+   */
   start (cb) {
     cb = cb || (() => {})
 
@@ -35,6 +46,12 @@ class Server {
     })
   }
 
+  /**
+   * Stop the server
+   *
+   * @param {function(err: Error)} [cb] - {@link https://github.com/hapijs/hapi/blob/v16.6.2/API.md#serverstopoptions-callback Hapi docs}
+   * @returns {void}
+   */
   stop (cb) {
     cb = cb || (() => {})
 

src/factory-client.js

@@ -3,8 +3,11 @@
 const request = require('superagent')
 const DaemonClient = require('./ipfsd-client')
 
-/*
+/** @ignore @typedef {import("./index").SpawnOptions} SpawnOptions */
+
+/**
  * Exposes the same Factory API but uses a remote endpoint to create the Daemons/Nodes
+ * @param {Object} options
  */
 class FactoryClient {
   constructor (options) {
@@ -31,9 +34,9 @@ class FactoryClient {
    * useful in browsers to be able to generate temp
    * repos manually
    *
-   * @param {String} type - the type of the node
-   * @param {function(Error, string)} callback
-   * @returns {undefined}
+   * @param {string} type - the type of the node
+   * @param {function(Error, string): void} callback
+   * @returns {void}
    */
   tmpDir (type, callback) {
     request
@@ -50,9 +53,8 @@ class FactoryClient {
   /**
    * Get the version of the IPFS Daemon.
    *
-   * @memberof FactoryDaemon
    * @param {Object} [options={}]
-   * @param {function(Error, string)} callback
+   * @param {function(Error, string): void} callback
    * @returns {undefined}
    */
   version (options, callback) {
@@ -75,6 +77,13 @@ class FactoryClient {
       })
   }
 
+  /**
+   * Spawn a remote daemon using ipfs-api
+   *
+   * @param {SpawnOptions} [options={}]
+   * @param {function(Error, DaemonClient)} callback
+   * @return {void}
+   */
   spawn (options, callback) {
     if (typeof options === 'function') {
       callback = options

src/factory-daemon.js

@@ -5,27 +5,20 @@ const clone = require('lodash.clone')
 const series = require('async/series')
 const path = require('path')
 const tmpDir = require('./utils/tmp-dir')
-
 const Daemon = require('./ipfsd-daemon')
 const defaultConfig = require('./defaults/config')
 const defaultOptions = require('./defaults/options')
 
-// TODO extract common functionality into base class
+/** @ignore @typedef {import("./index").SpawnOptions} SpawnOptions */
 
 /**
- * Spawn IPFS Daemons (either JS or Go)
+ * Creates an instance of FactoryDaemon.
  *
- * @namespace FactoryDaemon
+ * @param {Object} options
+ * @param {string} [options.type='go'] - 'go' or 'js'
+ * @param {string} [options.exec] - the path of the daemon executable
  */
 class FactoryDaemon {
-  /**
-   *
-   * @param {Object} options
-   *  - `type` string - 'go' or 'js'
-   *  - `exec` string (optional) - the path of the daemon executable
-   *  - `IpfsApi` - a custom IPFS API constructor
-   * @return {*}
-   */
   constructor (options) {
     if (options && options.type === 'proc') {
       throw new Error('This Factory does not know how to spawn in proc nodes')
@@ -41,8 +34,8 @@ class FactoryDaemon {
    * *Here for completeness*
    *
    * @param {String} type - the type of the node
-   * @param {function(Error, string)} callback
-   * @returns {undefined}
+   * @param {function(Error, string): void} callback
+   * @returns {void}
    */
   tmpDir (type, callback) {
     callback(null, tmpDir(type === 'js'))
@@ -51,10 +44,15 @@ class FactoryDaemon {
   /**
    * Get the version of the IPFS Daemon.
    *
-   * @memberof FactoryDaemon
    * @param {Object} [options={}]
-   * @param {function(Error, string)} callback
-   * @returns {undefined}
+   * @param {function(Error, (string|Object)): void} callback - Receives `Error` or `version` that might be one of the following:
+   * - if type is `go` a version string like `ipfs version <version number>`
+   * - if type is `js` a version string like `js-ipfs version <version number>`
+   * - if type is `proc` an object with the following properties:
+   *    - version - the ipfs version
+   *    - repo - the repo version
+   *    - commit - the commit hash for this version
+   * @returns {void}
    */
   version (options, callback) {
     if (typeof options === 'function') {
@@ -76,21 +74,9 @@ class FactoryDaemon {
   /**
    * Spawn an IPFS node, either js-ipfs or go-ipfs
    *
-   * Options are:
-   * - `init` bool - should the node be initialized
-   * - `initOptions` Object, it is expected to be of the form `{bits: <size>}`, which sets the desired key size
-   * - `start` bool - should the node be started
-   * - `repoPath` string - the repository path to use for this node, ignored if node is disposable
-   * - `disposable` bool - a new repo is created and initialized for each invocation
-   * - `defaultAddrs` bool (default false) - use the daemon default `Swarm` addrs
-   * - `config` - ipfs configuration options
-   * - `args` - array of cmd line arguments to be passed to ipfs daemon
-   * - `exec` string (optional) - path to the desired IPFS executable to spawn,
-   * this will override the `exec` set when creating the daemon controller factory instance
-   *
-   * @param {Object} [options={}] - various config options and ipfs config parameters
-   * @param {Function} callback(err, [`ipfs-api instance`, `Node (ctrl) instance`]) - a callback that receives an array with an `ipfs-instance` attached to the node and a `Node`
-   * @return {undefined}
+   * @param {SpawnOptions} [options={}] - Various config options and ipfs config parameters
+   * @param {function(Error, Daemon): void} callback - Callback receives Error or a Daemon instance, Daemon has a `api` property which is an `ipfs-api` instance.
+   * @returns {void}
    */
   spawn (options, callback) {
     if (typeof options === 'function') {