From b151dd84695a660f2524d17b14106faac8241a7c Mon Sep 17 00:00:00 2001 From: Hornwitser Date: Thu, 7 May 2020 17:59:36 +0200 Subject: [PATCH] Fix documentation Fix missing module declarations, broken lings, broken formating and incorrect scopes in the documentation. For modules split over several files it appears the only viable option is to use the memberof directive on each documented member and only declare the index file as a module. --- clusterctl.js | 9 +++++ docs/jsdoc.json | 3 +- lib/config/classes.js | 27 +++++++++++--- lib/config/definitions.js | 48 ++++++++++++++++++++++-- lib/config/index.js | 4 +- lib/errors.js | 39 ++++++++++++++++--- lib/factorio/index.js | 5 +++ lib/factorio/locale.js | 6 +-- lib/factorio/patch.js | 15 ++++++-- lib/factorio/server.js | 66 +++++++++++++++++++++++++-------- lib/fileOps/fileOps.js | 3 ++ lib/hash.js | 6 +++ lib/link/connectors.js | 16 ++++++++ lib/link/index.js | 5 +++ lib/link/link.js | 5 ++- lib/link/messages.js | 7 ++++ lib/luaTools.js | 5 +++ lib/plugin.js | 20 +++++++++- lib/schema.js | 34 +++++++++++++++++ master.js | 36 +++++++++++++----- plugins/global_chat/instance.js | 3 ++ slave.js | 12 ++++++ 22 files changed, 318 insertions(+), 56 deletions(-) diff --git a/clusterctl.js b/clusterctl.js index d02594db..0b5ecc43 100644 --- a/clusterctl.js +++ b/clusterctl.js @@ -1,3 +1,7 @@ +/** + * Command line interface for controlling a Clusterio cluster + * @module + */ const jwt = require("jsonwebtoken"); const fs = require("fs-extra"); const yargs = require("yargs"); @@ -16,6 +20,8 @@ const config = require("lib/config"); * * Formats a parsed Factorio output from lib/factorio into a readable * colorized output using terminal escape codes that can be printed. + * + * @private */ function formatOutputColored(output) { let time = ""; @@ -73,6 +79,7 @@ class Command { * @param client - link to master server to query instance on. * @param instanceName - string with name or id of instance. * @returns {number} instance ID. + * @private */ async function resolveInstance(client, instanceName) { let instanceId; @@ -104,6 +111,7 @@ async function resolveInstance(client, instanceName) { * @param client - link to master server to query slave on. * @param slaveName - string with name or id of slave. * @returns {number} slave ID. + * @private */ async function resolveSlave(client, slaveName) { let slaveId; @@ -324,6 +332,7 @@ commands = new Map([...commands.map(command => [command.name, command])]); /** * Connector for control connection to master server + * @private */ class ControlConnector extends link.WebSocketClientConnector { constructor(url, reconnectDelay, token) { diff --git a/docs/jsdoc.json b/docs/jsdoc.json index 88b1ded8..54216916 100644 --- a/docs/jsdoc.json +++ b/docs/jsdoc.json @@ -18,6 +18,7 @@ "plugins/", "routes/", "routes.js" - ] + ], + "excludePattern": "node_modules" } } diff --git a/lib/config/classes.js b/lib/config/classes.js index c43ec6be..13196729 100644 --- a/lib/config/classes.js +++ b/lib/config/classes.js @@ -1,7 +1,4 @@ -/** - * @file Configuration classes - * @author Hornwitser - */ +// Configuration classes "use strict"; const { basicType } = require("lib/helpers"); @@ -12,6 +9,9 @@ const { basicType } = require("lib/helpers"); * * Exception class for when invalid values are attempted to be set on a * field. + * + * @extends Error + * @memberof module:lib/config */ class InvalidValue extends Error { }; @@ -20,18 +20,26 @@ class InvalidValue extends Error { }; * * Exception class for when a group or field that does not exist is * attempted to be accessed. + * + * @extends Error + * @memberof module:lib/config */ class InvalidField extends Error { }; /** * Split the given string on the first instance of separator * - * Splits @p string on the first instance of @p separator and returns an + * Splits `string` on the first instance of `separator` and returns an * array consisting of the string up to the separator and the string * after the separator. Returns an array with the string and an empty * string if the separator is not present. * + * @param {string} separator - Separator to split string by. + * @param {string} string - String to split * @returns {Array} string split on separator. + * @memberof module:lib/config + * @private + * @inner */ function splitOn(separator, string) { let index = string.indexOf(separator); @@ -46,6 +54,8 @@ function splitOn(separator, string) { * * Represents a collection of ConfigGroup instances that can be * managed as one. + * + * @memberof module:lib/config */ class Config { constructor() { @@ -215,6 +225,8 @@ class Config { /** * Collection of related config entries + * + * @memberof module:lib/config */ class ConfigGroup { /** @@ -285,7 +297,7 @@ class ConfigGroup { * The field must be defined for the config group and the value is * type checked against the field definition. * - * @throws {InvalidValue} if value is not allowed for the field. + * @throws {module:lib/config.InvalidValue} if value is not allowed for the field. */ set(name, value) { let def = this.constructor._definitions.get(name); @@ -553,6 +565,9 @@ class ConfigGroup { * Grouping that includes per plugin fields clusterio uses to manage * plugins. This is currently only the enabled field. It is otherwise * identical to the ConfigGroup class. + * + * @extends module:lib/config.ConfigGroup + * @memberof module:lib/config */ class PluginConfigGroup extends ConfigGroup { static _initSubclass() { diff --git a/lib/config/definitions.js b/lib/config/definitions.js index 9c1dbc14..c20c61ed 100644 --- a/lib/config/definitions.js +++ b/lib/config/definitions.js @@ -1,7 +1,4 @@ -/** - * @file Core definitions for the configuration system - * @author Hornwitser - */ +// Core definitions for the configuration system "use strict"; const util = require("util"); @@ -12,6 +9,11 @@ const fs = require("fs-extra"); const classes = require("./classes"); +/** + * Master config group for {@link module:lib/config.MasterConfig} + * @extends module:lib/config.ConfigGroup + * @memberof module:lib/config + */ class MasterGroup extends classes.ConfigGroup { } MasterGroup.groupName = "master" MasterGroup.define({ @@ -103,10 +105,20 @@ MasterGroup.define({ }); MasterGroup.finalize(); +/** + * Master Config class + * @extends module:lib/config.Config + * @memberof module:lib/config + */ class MasterConfig extends classes.Config { } MasterConfig.registerGroup(MasterGroup); +/** + * Slave config group for {@link module:lib/config.SlaveConfig} + * @extends module:lib/config.ConfigGroup + * @memberof module:lib/config + */ class SlaveGroup extends classes.ConfigGroup {} SlaveGroup.groupName = "slave"; SlaveGroup.define({ @@ -160,10 +172,20 @@ SlaveGroup.define({ }); SlaveGroup.finalize(); +/** + * Slave Config class + * @extends module:lib/config.Config + * @memberof module:lib/config + */ class SlaveConfig extends classes.Config { } SlaveConfig.registerGroup(SlaveGroup); +/** + * Instance config group for {@link module:lib/config.InstanceConfig} + * @extends module:lib/config.ConfigGroup + * @memberof module:lib/config + */ class InstanceGroup extends classes.ConfigGroup { } InstanceGroup.groupName = "instance" InstanceGroup.define({ @@ -184,6 +206,11 @@ InstanceGroup.define({ }); InstanceGroup.finalize(); +/** + * Factorio config group for {@link module:lib/config.InstanceConfig} + * @extends module:lib/config.ConfigGroup + * @memberof module:lib/config + */ class FactorioGroup extends classes.ConfigGroup { } FactorioGroup.groupName = "factorio"; FactorioGroup.define({ @@ -221,6 +248,11 @@ FactorioGroup.define({ }); FactorioGroup.finalize(); +/** + * Instance config class + * @extends module:lib/config.Config + * @memberof module:lib/config + */ class InstanceConfig extends classes.Config { } InstanceConfig.registerGroup(InstanceGroup); InstanceConfig.registerGroup(FactorioGroup); @@ -242,6 +274,8 @@ function validateGroup(pluginInfo, groupName) { /** * Registers the config groups for the provided plugin infos + * + * @memberof module:lib/config */ function registerPluginConfigGroups(pluginInfos) { for (let pluginInfo of pluginInfos) { @@ -273,6 +307,8 @@ function registerPluginConfigGroups(pluginInfos) { /** * Lock configs from adding more groups and make them usable + * + * @memberof module:lib/config */ function finalizeConfigs() { MasterConfig.finalize(); @@ -285,6 +321,8 @@ function finalizeConfigs() { * * Can be passed to yargs.command to implement a config command. Use * handleConfigCommand to do the requested action. + * + * @memberof module:lib/config */ function configCommand(yargs) { yargs @@ -300,6 +338,8 @@ function configCommand(yargs) { * Handle yargs command * * Handle the actions that are made available by configCommand. + * + * @memberof module:lib/config */ async function handleConfigCommand(args, instance, configPath) { let command = args._[1]; diff --git a/lib/config/index.js b/lib/config/index.js index bbe1c364..f591436e 100644 --- a/lib/config/index.js +++ b/lib/config/index.js @@ -1,8 +1,8 @@ /** - * @file Configuration System + * Configuration System * @author Hornwitser + * @module lib/config */ - module.exports = { ...require("./classes"), ...require("./definitions"), diff --git a/lib/errors.js b/lib/errors.js index 19c9d27f..2b9a6bdd 100644 --- a/lib/errors.js +++ b/lib/errors.js @@ -3,10 +3,22 @@ * @module */ +/** + * Thrown by commands when they fail + * @static + */ class CommandError extends Error { } + +/** + * Thrown from requests sent when an error occured handling it + * @static + */ class RequestError extends Error { } -// Signal for messages that fail validation +/** + * Signal for messages that fail validation + * @static + */ class InvalidMessage extends Error { constructor(msg, errors) { super(msg); @@ -14,19 +26,34 @@ class InvalidMessage extends Error { } } -// Thrown from requests when the session it was sent on was lost. +/** + * Thrown from requests when the session it was sent on was lost + * @static + */ class SessionLost extends Error { } -// Thrown when WebSocket authentication failed +/** + * Thrown when WebSocket authentication failed + * @static + */ class AuthenticationFailed extends Error { } -// Errror class for known errors occuring during startup +/** + * Errror class for known errors occuring during startup + * @static + */ class StartupError extends Error { } -// Errors outside of our control. +/** + * Errors outside of our control + * @static + */ class EnvironmentError extends Error { } -// Errors caused by plugins +/** + * Errors caused by plugins + * @static + */ class PluginError extends Error { constructor(pluginName, original) { super(`PluginError: ${original.message}`); diff --git a/lib/factorio/index.js b/lib/factorio/index.js index 1e03bc70..b99f8803 100644 --- a/lib/factorio/index.js +++ b/lib/factorio/index.js @@ -1,3 +1,8 @@ +/** + * Library for interfacing with Factorio Servers and saves. + * @module lib/factorio + * @author Hornwitser + */ module.exports = { ...require('lib/factorio/locale'), ...require('lib/factorio/patch'), diff --git a/lib/factorio/locale.js b/lib/factorio/locale.js index 36ee8a1e..0bc6cef2 100644 --- a/lib/factorio/locale.js +++ b/lib/factorio/locale.js @@ -1,7 +1,4 @@ -/** - * Function for parsing factorio locale from a local factorio install - */ - +// Function for parsing factorio locale from a local factorio install "use strict"; const fs = require("fs-extra"); const path = require("path"); @@ -13,6 +10,7 @@ const ini = require("ini"); * @param {string} factorioDirectory * @param {string} languageCode * @param {function} callback + * @memberof module:lib/factorio */ async function getLocale(dataDir, languageCode) { if (typeof dataDir !== "string") throw new TypeError("dataDir must be a string"); diff --git a/lib/factorio/patch.js b/lib/factorio/patch.js index 2d5c1957..e7545be1 100644 --- a/lib/factorio/patch.js +++ b/lib/factorio/patch.js @@ -1,7 +1,4 @@ -/** - * Library for patching Factorio saves with scenario code. - * @author Hornwitser - */ +// Library for patching Factorio saves with scenario code. "use strict"; const events = require("events"); @@ -31,6 +28,9 @@ const knownScenarios = { * contained in. Throws an error if there are multiple such folders. * * @returns {string} name of the root folder. + * @memberof module:lib/factorio + * @private + * @inner */ function findRoot(zip) { let root = null; @@ -60,6 +60,9 @@ function findRoot(zip) { * Generates control.lua code for loading the Clusterio modules * * @param {Object} patchInfo - The patch info files's json content + * @memberof module:lib/factorio + * @private + * @inner */ function generateLoader(patchInfo) { let lines = [ @@ -107,6 +110,9 @@ function generateLoader(patchInfo) { * their dependents. Throws an error if this is not possible. * * @param {Array} modules - Array of modules to reorder + * @memberof module:lib/factorio + * @private + * @inner */ function reorderDependencies(modules) { let index = 0; @@ -202,6 +208,7 @@ function reorderDependencies(modules) { * * @param {string} savePath - Path to the Factorio save to patch. * @param {Array} modules - Description of the modules to patch. + * @memberof module:lib/factorio */ async function patch(savePath, modules) { let zip = await jszip.loadAsync(await fs.readFile(savePath)); diff --git a/lib/factorio/server.js b/lib/factorio/server.js index 8f7a6540..bf31d557 100644 --- a/lib/factorio/server.js +++ b/lib/factorio/server.js @@ -1,9 +1,4 @@ -/** - * Factorio interfaces - * - * @module - */ - +// Factorio Server interface "use strict"; const fs = require("fs-extra"); const child_process = require("child_process"); @@ -20,6 +15,10 @@ const errors = require("lib/errors"); /** * Determines the version of Factorio the datadir is pointing to by * reading the changelog.txt in it. + * + * @memberof module:lib/factorio + * @private + * @inner */ async function getVersion(changelogPath) { let changelog; @@ -47,6 +46,10 @@ async function getVersion(changelogPath) { /** * Comparison function for sorting Factorio version strings + * + * @memberof module:lib/factorio + * @private + * @inner */ function versionOrder(a, b) { let aParts = a.split(".").map(s => Number.parseInt(s, 10)); @@ -70,6 +73,10 @@ function versionOrder(a, b) { * * Searches the given factorio dir for an installation of Factorio of * the target version. + * + * @memberof module:lib/factorio + * @private + * @inner */ async function findVersion(factorioDir, targetVersion) { @@ -125,6 +132,9 @@ async function findVersion(factorioDir, targetVersion) { * RFC 6335. * * @return {number} a number in the range 49152 to 65535. + * @memberof module:lib/factorio + * @private + * @inner */ function randomDynamicPort() { const start = 49152; @@ -141,6 +151,9 @@ function randomDynamicPort() { * * @param {number} length - the length of the password to generate. * @return {string} password of the given length + * @memberof module:lib/factorio + * @private + * @inner */ async function generatePassword(length) { function validChar(byte) { @@ -179,6 +192,10 @@ async function generatePassword(length) { * Data is streamed via the data method, and once the stream ends the * end method should be called. This ensures an unterminated line at * the end of the stream is passed to the callback. + * + * @memberof module:lib/factorio + * @private + * @inner */ class LineSplitter { @@ -253,6 +270,9 @@ class LineSplitter { * @param {string} source - Passed into the output structure as source * * @returns {object} - An object with interpeted data. + * @memberof module:lib/factorio + * @private + * @inner */ function parseOutput(line, source) { let output = { @@ -425,15 +445,17 @@ const outputHeuristics = [ * stopping and sending commands to the server. It does not deal with * creating or managing servers, or downloading Factorio. * - * This is an events emitter with the following events: - * stdout - invoked when Factorio outputs a line to stdout - * stderr - invoked when Factorio outputs a line to stderr - * output - invoked with parsed output from Factorio - * rcon-ready - invoked when the RCON client has connected - * game-ready - invoked when the server is finished starting up - * autosave-start - invoked when the server starts an autosave - * autosave-fnished - invoked when the autosave finished - * exit - invoked when the sterver has exited + * This is an EventEmitter with the following events: + * - stdout - invoked when Factorio outputs a line to stdout + * - stderr - invoked when Factorio outputs a line to stderr + * - output - invoked with parsed output from Factorio + * - rcon-ready - invoked when the RCON client has connected + * - game-ready - invoked when the server is finished starting up + * - autosave-start - invoked when the server starts an autosave + * - autosave-fnished - invoked when the autosave finished + * - exit - invoked when the sterver has exited + * @extends events.EventEmitter + * @memberof module:lib/factorio */ class FactorioServer extends events.EventEmitter { /** @@ -442,6 +464,12 @@ class FactorioServer extends events.EventEmitter { * @param {string} factorioDir - Directory of the Factorio install(s). * @param {string} writeDir - Directory to write runtime data to. * @param {object} options - Optional parameters. + * @param {string} options.version - + * Version of Factorio to use. Can also be the string "latest" to + * use the latest version found in `factorioDir`. + * @param {number} options.gamePort - UDP port to host game on. + * @param {number} options.rconPort - TCP port to use for RCON. + * @param {string} options.rconPassword - Password use for RCON. */ constructor(factorioDir, writeDir, options) { super(); @@ -454,8 +482,11 @@ class FactorioServer extends events.EventEmitter { this._dataDir = null; this._targetVersion = options.version || "latest"; + /** UDP port used for hosting the Factorio game server on */ this.gamePort = options.gamePort || randomDynamicPort(); + /** TCP port used for RCON on the Factorio game server */ this.rconPort = options.rconPort || randomDynamicPort(); + /** Password used for RCON on the Factorio game server */ this.rconPassword = options.rconPassword; this._state = "new"; this._server = null; @@ -603,6 +634,7 @@ class FactorioServer extends events.EventEmitter { * Initialize class instance * * Must be called before instances of this class can be used. + * @throws {Error} if the requested version of Factorio was not found. */ async init() { this._check(["new"]); @@ -612,7 +644,9 @@ class FactorioServer extends events.EventEmitter { } /** - * The version of Factorio that was detected + * The version of Factorio in use. This will be the actual version if + * "latest" (the default) was specified as `factorioVersion` to the + * constructor. */ get version() { return this._version; diff --git a/lib/fileOps/fileOps.js b/lib/fileOps/fileOps.js index 251991a3..ed42b794 100644 --- a/lib/fileOps/fileOps.js +++ b/lib/fileOps/fileOps.js @@ -1,3 +1,6 @@ +/** + * @module lib/fileOps + */ const fs = require("fs-extra"); const path = require("path"); diff --git a/lib/hash.js b/lib/hash.js index 9cf9c4bf..9bb694ed 100644 --- a/lib/hash.js +++ b/lib/hash.js @@ -1,3 +1,7 @@ +/** + * Hashing functions + * @module + */ const crypto = require('crypto'); const fs = require('fs'); @@ -6,6 +10,7 @@ const fs = require('fs'); * Returns a promise that resolves to the SHA1 hash of the stream given * * @param stream - Node stream of the content to hash. + * @returns {Promise} hash of the stream. */ function hashStream(stream) { return new Promise(function(resolve, reject) { @@ -28,6 +33,7 @@ function hashStream(stream) { * Returns a promise that resolves to the SHA1 hash of the file given by path * * @param {string} path - Path to the file to hash. + * @returns {Promise} hash of the file given. */ function hashFile(path) { return hashStream(fs.createReadStream(path)); diff --git a/lib/link/connectors.js b/lib/link/connectors.js index d7afe5fc..1b6b4d78 100644 --- a/lib/link/connectors.js +++ b/lib/link/connectors.js @@ -1,3 +1,4 @@ +// Connection adapters for Links "use strict"; const events = require("events"); const WebSocket = require("ws"); @@ -6,6 +7,12 @@ const schema = require("lib/schema"); const errors = require("lib/errors"); +/** + * Base connector for links + * + * @extends events.EventEmitter + * @memberof module:lib/link + */ class WebSocketBaseConnector extends events.EventEmitter { constructor() { super(); @@ -112,6 +119,9 @@ class WebSocketBaseConnector extends events.EventEmitter { /** * Connector for master server clients + * + * @extends module:lib/link.WebSocketBaseConnector + * @memberof module:lib/link */ class WebSocketClientConnector extends WebSocketBaseConnector { constructor(url, reconnectDelay) { @@ -397,6 +407,12 @@ class WebSocketClientConnector extends WebSocketBaseConnector { } } +/** + * Connector for in-memory local links + * + * @extends events.EventEmitter + * @memberof module:lib/link + */ class VirtualConnector extends events.EventEmitter { constructor() { super(); diff --git a/lib/link/index.js b/lib/link/index.js index 132ff5d0..e5c18c5f 100644 --- a/lib/link/index.js +++ b/lib/link/index.js @@ -1,3 +1,8 @@ +/** + * Library for message based communication between nodes + * @module lib/link + * @author Hornwitser + */ module.exports = { ...require('lib/link/link'), ...require('lib/link/messages'), diff --git a/lib/link/link.js b/lib/link/link.js index d36d8b56..347efef4 100644 --- a/lib/link/link.js +++ b/lib/link/link.js @@ -1,3 +1,4 @@ +// Implementation of Link class "use strict"; const schema = require("lib/schema"); @@ -15,6 +16,8 @@ const messages = require("lib/link/messages"); /** * Common interface for server and client connections + * + * @memberof module:lib/link */ class Link { constructor(source, target, connector) { @@ -59,7 +62,7 @@ class Link { * Validates and invokes the handler and/or waiters for a message that has * been received. An unhandled message is considered to be an error. * - * @throws {InvalidMessage} + * @throws {module:lib/errors.InvalidMessage} * if validation failed, is missing, the message is invalid, or no * handlers/waiters were invoked to handle the message. */ diff --git a/lib/link/messages.js b/lib/link/messages.js index 365bfa6a..8edf569e 100644 --- a/lib/link/messages.js +++ b/lib/link/messages.js @@ -1,3 +1,4 @@ +// Message definitions for links "use strict"; const schema = require("lib/schema"); const errors = require("lib/errors"); @@ -7,6 +8,8 @@ const errors = require("lib/errors"); * * A request-response message that can be innitated by either party of the * link. + * + * @memberof module:lib/link */ class Request { @@ -353,6 +356,8 @@ messages.getMetrics = new Request({ * * A one way message without any response or recipt confirmation that * can be innitiated by either party of the link. + * + * @memberof module:lib/link */ class Event { @@ -555,6 +560,8 @@ messages.instanceOutput = new Event({ * to the link. The handler used for the messageis looked up on the * link instance as the concatenation of the name of the message, the * name of message class, and 'Handler'. + * + * @memberof module:lib/link */ function attachAllMessages(link) { for (let [name, message] of Object.entries(messages)) { diff --git a/lib/luaTools.js b/lib/luaTools.js index 8165beb5..7566e03e 100644 --- a/lib/luaTools.js +++ b/lib/luaTools.js @@ -1,3 +1,8 @@ +/** + * Utilities for dealing with Lua + * @module + */ + /** * Escapes a string for inclusion into a lua string */ diff --git a/lib/plugin.js b/lib/plugin.js index 41661db3..7dd6a3ad 100644 --- a/lib/plugin.js +++ b/lib/plugin.js @@ -11,6 +11,7 @@ const errors = require("lib/errors"); /** * Base class for instance plugins + * @static */ class BaseInstancePlugin { constructor(info, instance, slave) { @@ -21,7 +22,7 @@ class BaseInstancePlugin { /** * Instance the plugin started for - * @type {Instance} + * @type {module:slave~Instance} */ this.instance = instance; @@ -31,7 +32,7 @@ class BaseInstancePlugin { * With the exepction of accessing the slave's config you should * avoid ineracting with the slave object directly. * - * @type {Slave} + * @type {module:slave~Slave} */ this.slave = slave; } @@ -95,6 +96,10 @@ class BaseInstancePlugin { async onOutput(output) { } } +/** + * Base class for master plugins + * @static + */ class BaseMasterPlugin { constructor(info, master, metrics) { this.info = info; @@ -138,6 +143,7 @@ class BaseMasterPlugin { * function be called again. * * @returns {Map} mapping of plugin name to info module. + * @static */ async function loadPluginInfos(baseDir) { let plugins = []; @@ -167,6 +173,16 @@ async function loadPluginInfos(baseDir) { return plugins; } +/** + * Attach plugin messages + * + * Attaches all messages defined in the `.message` property of the + * `pluginInfo` passed with handlers taken from `pluin`. + * + * @param {module:lib/link.Link} link - Link to attach handlers to. + * @param {object} pluginInfo - Plugin info object. + * @param plugin - The instance of the plugin to use handlers from. + */ function attachPluginMessages(link, pluginInfo, plugin) { let messageDefinitions = pluginInfo.messages || []; for (let [name, messageFormat] of Object.entries(messageDefinitions)) { diff --git a/lib/schema.js b/lib/schema.js index 07e649f6..84fc6de0 100644 --- a/lib/schema.js +++ b/lib/schema.js @@ -1,3 +1,7 @@ +/** + * JSON schemas used for validating link messages + * @module + */ const ajv = new (require('ajv'))({ verbose: true, format: "full", @@ -24,8 +28,20 @@ const messageSchema = { }, }; +/** + * Validator for message schemas + * @function + * @param {Object} obj - Object to validate + * @returns {boolean} True if object passed validation. + */ const message = ajv.compile(messageSchema); +/** + * Validator for heartbeat messages + * @function + * @param {Object} obj - Object to validate + * @returns {boolean} True if object passed validation. + */ const heartbeat = ajv.compile({ $schema: "http://json-schema.org/draft-07/schema#", title: "Heartbeat", @@ -47,6 +63,12 @@ const heartbeat = ajv.compile({ }, }); +/** + * Validator for server sent part of handshake + * @function + * @param {Object} obj - Object to validate + * @returns {boolean} True if object passed validation. + */ const serverHandshake = ajv.compile({ $schema: "http://json-schema.org/draft-07/schema#", title: "Server Handshake", @@ -104,6 +126,12 @@ const serverHandshake = ajv.compile({ ], }); +/** + * Validator for client sent part of handshake + * @function + * @param {Object} obj - Object to validate + * @returns {boolean} True if object passed validation. + */ const clientHandshake = ajv.compile({ $schema: "http://json-schema.org/draft-07/schema#", title: "Client Message", @@ -162,6 +190,12 @@ const clientHandshake = ajv.compile({ module.exports = { + /** + * Compile JSON schema into validator + * @function + * @param {Object} schema - JSON schema to create validator for. + * @returns {Function} Validator for the schema. + */ compile: ajv.compile.bind(ajv), message, diff --git a/master.js b/master.js index f2dba036..b6885823 100644 --- a/master.js +++ b/master.js @@ -1,13 +1,16 @@ /** -Clusterio master server. Facilitates communication between slaves through -a webserver, storing data related to slaves like production graphs. - -@module -@author Danielv123 - -@example -node master -*/ + * Clusterio master server + * + * Facilitates communication between slaves and control of the cluster + * through WebSocet connections, and hosts a webserver for browser + * interfaces and Prometheus statistics export. It is remotely controlled + * by {@link module:clusterctl}. + * + * @module + * @author Danielv123, Hornwitser + * @example + * node master run + */ // Attempt updating // const updater = require("./updater"); @@ -345,6 +348,11 @@ app.get("/api/getFactorioLocale", function(req,res){ } }); +/** + * Base class for master server connections + * + * @extends module:lib/link.Link + */ class BaseConnection extends link.Link { constructor(target, connector) { super('master', target, connector); @@ -574,6 +582,11 @@ class ControlConnection extends BaseConnection { } var slaveConnections = new Map(); +/** + * Represents the connection to a slave + * + * @extends module:master~BaseConnection + */ class SlaveConnection extends BaseConnection { constructor(registerData, connector) { super('slave', connector); @@ -647,7 +660,8 @@ const wss = new WebSocket.Server({ * * @param value - value to test. * @returns {Boolean} - * true if value is an integer between -2**31 and 2**31-1. + * true if value is an integer between -231 and + * 231-1. */ function isInteger(value) { return value | 0 === value; @@ -656,6 +670,8 @@ function isInteger(value) { /** * Connector for master server connections + * + * @extends module:lib/link.WebSocketBaseConnector */ class WebSocketServerConnector extends link.WebSocketBaseConnector { constructor(socket, sessionId) { diff --git a/plugins/global_chat/instance.js b/plugins/global_chat/instance.js index e44ed210..2674a03d 100644 --- a/plugins/global_chat/instance.js +++ b/plugins/global_chat/instance.js @@ -1,3 +1,6 @@ +/** + * @module + */ const plugin = require("lib/plugin"); const luaTools = require("lib/luaTools"); diff --git a/slave.js b/slave.js index 78041eb1..716d092e 100644 --- a/slave.js +++ b/slave.js @@ -1,3 +1,15 @@ +/** + * Clusterio slave + * + * Connects to the master server and hosts Factorio servers that can + * communicate with the cluster. It is remotely controlled by {@link + * module:master}. + * + * @module + * @author Danielv123, Hornwitser + * @example + * node slave run + */ const fs = require('fs-extra'); const path = require('path'); const yargs = require("yargs");