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.
This commit is contained in:
Hornwitser committed 2020-05-08 17:28:06 +02:00
1 parent 7a9b6592e6
commit b151dd8469
22 files changed
+318 -56

No files matched your search

+21 -6
View File
@@ -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() {
+44 -4
View File
@@ -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];
+2 -2
View File
@@ -1,8 +1,8 @@
/**
* @file Configuration System
* Configuration System
* @author Hornwitser
* @module lib/config
*/
module.exports = {
...require("./classes"),
...require("./definitions"),