From 96d60e5428169fe898c85d209278260b665b00fb Mon Sep 17 00:00:00 2001 From: Danielv123 Date: Mon, 6 Nov 2017 23:37:13 +0100 Subject: [PATCH] Attempted to add some JSDOC docs, npm run docs/livedocs --- client.js | 4 ++-- lib/manager/modManager.js | 10 ++++++++- master.js | 47 ++++++++++++++++++++++++++++++++++----- package.json | 5 ++++- 4 files changed, 57 insertions(+), 9 deletions(-) diff --git a/client.js b/client.js index 7b6bf66b..a17554b9 100644 --- a/client.js +++ b/client.js @@ -392,8 +392,8 @@ function instanceManagement() { } let pluginConfig = require("./sharedPlugins/" + pluginDirectories[i] + "/config.js"); - let arguments = pluginConfig.arguments || []; - plugins.push(child_process.spawn(pluginConfig.binary, arguments, { + let args = pluginConfig.args || []; + plugins.push(child_process.spawn(pluginConfig.binary, args, { cwd: "./sharedPlugins/"+pluginDirectories[i], stdio: ['pipe', 'pipe', 'pipe'], })); diff --git a/lib/manager/modManager.js b/lib/manager/modManager.js index 57ba5e2c..9a88b989 100644 --- a/lib/manager/modManager.js +++ b/lib/manager/modManager.js @@ -1,3 +1,8 @@ +/** +Provides tools to manage mods in a clusterio install +@module modManager +*/ + const rightpad = require("right-pad"); const asTable = require("as-table").configure({delimiter: ' | '}); const moment = require("moment"); @@ -7,7 +12,10 @@ const fileOps = require("./../fileOps.js"); const config = require("./../../config"); const instances = fileOps.getDirectoriesSync("./instances/"); - +/** +Lists mods for an instance +@param {string} instance - Name of the instance or "shared" +*/ module.exports.listMods = function(instance){ if(instance && instances.includes(instance)){ factorioAPI.init(false, 'instances/'+instance+'/mods', 'instances/'+instance+'/saves', '0.15.37'); diff --git a/master.js b/master.js index 93089bbd..bed44530 100644 --- a/master.js +++ b/master.js @@ -1,3 +1,12 @@ +/** +Clusterio master server. Facilitates communication between slaves through +a webserver, storing data related to slaves like production graphs and +combinator signals. + +@module clusterioMaster +@author Danielv123 +*/ + // Set the process title, shows up as the title of the CMD window on windows // and as the process name in ps/top on linux. process.title = "clusterioMaster"; @@ -348,7 +357,12 @@ app.post("/api/readSignal", function(req,res) { // console.log(docs); }); }); +/** +GET endpoint to read the masters current inventory of items. +@alias api/inventory +@returns {object[]} JSON [{name:"iron-plate", count:100},{name:"copper-plate",count:5}] +*/ // endpoint for getting an inventory of what we got app.get("/api/inventory", function(req, res) { res.header("Access-Control-Allow-Origin", "*"); @@ -371,6 +385,15 @@ app.get("/api/inventoryAsObject", function(req, res) { // post flowstats here for production graphs // {timestamp: Date, slaveID: string, data: {"item":number}} +/** +POST endpoint to log production graph statistics. Should contain a timestamp +gathered from Date.now(), a slaveID (also reffered to as "unique") and of +course the timeSeries data. + +@alias api/logStats +@param {object} JSON {timestamp: Date.now(), slaveID: "string", data: {"item": number}} +@returns {string} failure +*/ app.post("/api/logStats", function(req,res) { if(typeof req.body == "object" && req.body.slaveID && req.body.timestamp && req.body.data) { if(Number(req.body.timestamp) != NaN){ @@ -383,13 +406,21 @@ app.post("/api/logStats", function(req,res) { console.log("inserted: " + req.body.slaveID + " | " + req.body.timestamp); } else { console.log("error invalid timestamp " + req.body.timestamp); - res.send(failure); + res.send("failure"); } } else { res.send("failure"); } }); // {slaveID: string, fromTime: Date, toTime, Date} +/** +POST endpoint to get timeSeries statistics stored on the master. Can give production +graphs and other IO statistics. + +@alias api/getStats +@param {object} JSON +@returns {object} - with statistics +*/ app.post("/api/getStats", function(req,res) { if(typeof req.body == "string"){ req.body = JSON.parse(req.body); @@ -451,10 +482,16 @@ app.post("/api/getStats", function(req,res) { } }); -// Modified version of getStats which feeds the web interface production graphs -// at /nodes. It is like getStats but it does not report items which were not -// produced at the moment of recording. (This is to save space, the 0-items were -// making up about 92% of the response body weight.) +/** +POST endpoint. Modified version of api/getStats which feeds the web interface production graphs +at /nodes. It is like getStats but it does not report items which were not +produced at the moment of recording. (This is to save space, the 0-items were +making up about 92% of the response body weight.) + +@alias api/getTimelineStats +@param {object} JSON {slaveID:1941029, fromTime: ???, toTime: ???} +@returns {object[]} timeseries where each entry is a set point in time. +*/ app.post("/api/getTimelineStats", function(req,res) { console.log(req.body); if(typeof req.body == "object" && req.body.slaveID) { diff --git a/package.json b/package.json index e092771d..ca461709 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,9 @@ "scripts": { "test": "./node_modules/.bin/istanbul cover ./node_modules/mocha/bin/_mocha -- \"./{,!(node_modules)/**/}*.spec.js\" -R spec || echo .", "start": "echo Run node client.js start [instance] to start slaves && node master.js", - "cover": "./node_modules/.bin/istanbul cover ./node_modules/mocha/bin/_mocha -- \"./{,!(node_modules)/**/}*.spec.js\" -R spec || echo . && codecov -t f7b38085-36eb-4d72-84e6-64721910171e" + "cover": "./node_modules/.bin/istanbul cover ./node_modules/mocha/bin/_mocha -- \"./{,!(node_modules)/**/}*.spec.js\" -R spec || echo . && codecov -t f7b38085-36eb-4d72-84e6-64721910171e", + "docs": "documentation build index.js -f html -o docs", + "livedocs": "documentation serve --watch *.js" }, "keywords": [ "factorio" @@ -53,6 +55,7 @@ }, "devDependencies": { "chai": "^3.5.0", + "documentation": "^5.3.3", "istanbul": "^0.4.5", "mocha": "^3.5.3", "mocha-sinon": "^2.0.0",