Fix JSDoc issues

Fix missing documentation for parameters and return types, incorect
config and errors in type definitions.
This commit is contained in:
Hornwitser committed 2020-06-17 20:53:18 +02:00
1 parent 3dba92a03d
commit 703fda43ad
20 files changed
+193 -52

No files matched your search

+51 -11
View File
@@ -120,6 +120,8 @@ class Config extends events.EventEmitter {
/**
* Serialize the config to a plain JavaScript object
*
* @returns {Object} JSON serializable representation of the config.
*/
serialize() {
let groups = [...this._unknownGroups.values()];
@@ -135,6 +137,9 @@ class Config extends events.EventEmitter {
*
* Updates all groups in the config with groups in the serialized
* config passed.
*
* @param {Object} serializedConfig - Output from .serialize().
* @param {boolean} notify - Invoke fieldChanged events if true.
*/
update(serializedConfig, notify) {
this._validate(serializedConfig);
@@ -150,6 +155,9 @@ class Config extends events.EventEmitter {
/**
* Get the value for a config field
*
* @param {string} name - Name of field to get.
* @returns {*} the value for the field.
*/
get(name) {
let [group, field] = splitOn(".", name);
@@ -158,22 +166,32 @@ class Config extends events.EventEmitter {
/**
* Set the value for a config field
*
* @param {string} name - Name of field to set.
* @param {*} value - the value to set on field
*/
set(name, value) {
let [group, field] = splitOn(".", name);
return this.group(group).set(field, value);
this.group(group).set(field, value);
}
/**
* Set property of an object value for a config field
*
* @param {string} name - Name of field to set property on.
* @param {string} prop - Name of property to set on field.
* @param {*} value - the value to set the property to.
*/
setProp(name, prop, value) {
let [group, field] = splitOn(".", name);
return this.group(group).setProp(field, prop, value);
this.group(group).setProp(field, prop, value);
}
/**
* Get the config group instance with the given name
*
* @param {string} name - Name of group to get.
* @returns {module:lib/config.ConfigGroup} config group.
*/
group(name) {
if (!this._initialized) {
@@ -223,6 +241,8 @@ class Config extends events.EventEmitter {
*
* Adds the ConfigGroup to this config as a group that will get
* initialized, loaded and serialized with this config class.
*
* @param {module:lib/config.ConfigGroup} group - class to register.
*/
static registerGroup(group) {
this._initSubclass();
@@ -261,7 +281,7 @@ class ConfigGroup {
* After the creation of the new config group you have to call
* either .init() or .load() on it in order to fully initialize it.
*/
constructor(serializedGroup) {
constructor() {
if (!this.constructor._finalized) {
throw new Error(`Cannot instantiate incomplete ConfigGroup class ${this.constructor.name}`);
}
@@ -276,6 +296,8 @@ class ConfigGroup {
*
* Computes and assigns the initial values for all fields of the
* config group.
*
* @param {module:lib/config.Config} config - Config group belongs to.
*/
async init(config) {
this._config = config;
@@ -303,6 +325,10 @@ class ConfigGroup {
* Loads all the values from the passed serialized version of the
* group and then initializes any possible missing fields from it to
* their default values.
*
* @param {module:lib/config.Config} config - Config group belongs to.
* @param {Object} serializedGroup -
* Result from a previous call to .serialize().
*/
async load(config, serializedGroup) {
this.update(serializedGroup, false);
@@ -320,6 +346,9 @@ class ConfigGroup {
/**
* Get value for field
*
* @param {string} name - Name of field to get.
* @returns {*} Value stored for the field.
*/
get(name) {
if (!this.constructor._definitions.has(name)) {
@@ -335,6 +364,8 @@ class ConfigGroup {
* The field must be defined for the config group and the value is
* type checked against the field definition.
*
* @param {string} name - Name of field to set.
* @param {*} value - Value to set for field.
* @throws {module:lib/config.InvalidField} if field is not defined.
* @throws {module:lib/config.InvalidValue} if value is not allowed for the field.
*/
@@ -397,6 +428,9 @@ class ConfigGroup {
* Update value of stored object field by setting the specified property
* on it. The field must be defined as an object for the config group.
*
* @param {string} name - Name of field to set property on.
* @param {string} prop - Name of property to set on field.
* @param {*} value - the value to set the property to.
* @throws {module:lib/config.InvalidField} if field is not defined.
* @throws {module:lib/config.InvalidValue} if field is not an object.
*/
@@ -430,6 +464,10 @@ class ConfigGroup {
*
* Overwrites the values of all the fields in this config group that
* has a valid value in the passed serialized group with that value.
*
* @param {Object} serializedGroup -
* Result from a previous call to .serialize().
* @param {boolean} notify - Invoke fieldChanged events if true.
*/
update(serializedGroup, notify) {
if (basicType(serializedGroup) !== "object") {
@@ -475,6 +513,8 @@ class ConfigGroup {
/**
* Serialize the config to a plain JavaScript object
*
* @returns {Object} JSON serializable representation of the group.
*/
serialize() {
let fields = {};
@@ -517,23 +557,23 @@ class ConfigGroup {
/**
* Define a new configuration field
*
* The following properties are supported:
* - type:
* @param {Object} item - Field definition.
* @param {string} item.type -
* string declaring the type of the config value, supports
* boolean, string, number and object.
* - name:
* @param {string} item.name -
* Name of the configuration field. Should follow the
* lower_case_underscore style.
* - title:
* @param {string} item.title -
* Text used to identify the config field in user interfaces.
* - description:
* @param {string} item.description -
* Text used to describe the config field in user interfaces.
* - enum (optional):
* @param {Array=} item.enum -
* Array of all values that are acceptible. Useful for making
* enumerated values.
* - optional (optional):
* @param {boolean=} item.optional -
* True if this field can be set to null. Defaults to false.
* - initial_value (optional):
* @param {*=} item.initial_value -
* Value this config field should take in a newly initialized
* config. This can also be an async function returning the
* value to use.