kenmirrors/MagicMirror
1
0
Fork 0
mirror of https://github.com/MichMich/MagicMirror.git synced 2025-06-28 04:02:12 +00:00
Code Issues Projects Releases Wiki Activity

Cleanup main jsdoc

Browse Source
This commit is contained in:
rejas 2020-08-01 17:06:46 +02:00
parent 935c9b6a42
commit 02779ef725
1 changed files with 85 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

167
js/main.js
View File

@ -11,9 +11,8 @@ var MM = (function () {
/* Private Methods */ /* Private Methods */
/* createDomObjects() /**
* Create dom objects for all modules that * Create dom objects for all modules that are configured for a specific position.
* are configured for a specific position.
*/ */
var createDomObjects = function () { var createDomObjects = function () {
var domCreationPromises = []; var domCreationPromises = [];
@ -65,10 +64,12 @@ var MM = (function () {
}); });
}; };
/* selectWrapper(position) /**
* Select the wrapper dom object for a specific position. * Select the wrapper dom object for a specific position.
* *
* argument position string - The name of the position. * @param {string} position The name of the position.
*
* @returns {HTMLElement} the wrapper element
*/ */
var selectWrapper = function (position) { var selectWrapper = function (position) {
var classes = position.replace("_", " "); var classes = position.replace("_", " ");
@ -81,13 +82,13 @@ var MM = (function () {
} }
}; };
/* sendNotification(notification, payload, sender) /**
* Send a notification to all modules. * Send a notification to all modules.
* *
* argument notification string - The identifier of the notification. * @param {string} notification The identifier of the notification.
* argument payload mixed - The payload of the notification. * @param {*} payload The payload of the notification.
* argument sender Module - The module that sent the notification. * @param {Module} sender The module that sent the notification.
* argument sendTo Module - The module to send the notification to. (optional) * @param {Module} [sendTo] The (optional) module to send the notification to.
*/ */
var sendNotification = function (notification, payload, sender, sendTo) { var sendNotification = function (notification, payload, sender, sendTo) {
for (var m in modules) { for (var m in modules) {
@ -98,13 +99,13 @@ var MM = (function () {
} }
}; };
/* updateDom(module, speed) /**
* Update the dom for a specific module. * Update the dom for a specific module.
* *
* argument module Module - The module that needs an update. * @param {Module} module The module that needs an update.
* argument speed Number - The number of microseconds for the animation. (optional) * @param {number} [speed] The (optional) number of microseconds for the animation.
* *
* return Promise - Resolved when the dom is fully updated. * @returns {Promise} Resolved when the dom is fully updated.
*/ */
var updateDom = function (module, speed) { var updateDom = function (module, speed) {
return new Promise(function (resolve) { return new Promise(function (resolve) {
@ -126,15 +127,15 @@ var MM = (function () {
}); });
}; };
/* updateDomWithContent(module, speed, newHeader, newContent) /**
* Update the dom with the specified content * Update the dom with the specified content
* *
* argument module Module - The module that needs an update. * @param {Module} module The module that needs an update.
* argument speed Number - The number of microseconds for the animation. (optional) * @param {number} [speed] The (optional) number of microseconds for the animation.
* argument newHeader String - The new header that is generated. * @param {string} newHeader The new header that is generated.
* argument newContent Domobject - The new content that is generated. * @param {HTMLElement} newContent The new content that is generated.
* *
* return Promise - Resolved when the module dom has been updated. * @returns {Promise} Resolved when the module dom has been updated.
*/ */
var updateDomWithContent = function (module, speed, newHeader, newContent) { var updateDomWithContent = function (module, speed, newHeader, newContent) {
return new Promise(function (resolve) { return new Promise(function (resolve) {
@ -165,14 +166,14 @@ var MM = (function () {
}); });
}; };
/* moduleNeedsUpdate(module, newContent) /**
* Check if the content has changed. * Check if the content has changed.
* *
* argument module Module - The module to check. * @param {Module} module The module to check.
* argument newHeader String - The new header that is generated. * @param {string} newHeader The new header that is generated.
* argument newContent Domobject - The new content that is generated. * @param {HTMLElement} newContent The new content that is generated.
* *
* return bool - Does the module need an update? * @returns {boolean} True if the module need an update, false otherwise
*/ */
var moduleNeedsUpdate = function (module, newHeader, newContent) { var moduleNeedsUpdate = function (module, newHeader, newContent) {
var moduleWrapper = document.getElementById(module.identifier); var moduleWrapper = document.getElementById(module.identifier);
@ -197,12 +198,12 @@ var MM = (function () {
return headerNeedsUpdate || contentNeedsUpdate; return headerNeedsUpdate || contentNeedsUpdate;
}; };
/* moduleNeedsUpdate(module, newContent) /**
* Update the content of a module on screen. * Update the content of a module on screen.
* *
* argument module Module - The module to check. * @param {Module} module The module to check.
* argument newHeader String - The new header that is generated. * @param {string} newHeader The new header that is generated.
* argument newContent Domobject - The new content that is generated. * @param {HTMLElement} newContent The new content that is generated.
*/ */
var updateModuleContent = function (module, newHeader, newContent) { var updateModuleContent = function (module, newHeader, newContent) {
var moduleWrapper = document.getElementById(module.identifier); var moduleWrapper = document.getElementById(module.identifier);
@ -223,12 +224,13 @@ var MM = (function () {
} }
}; };
/* hideModule(module, speed, callback) /**
* Hide the module. * Hide the module.
* *
* argument module Module - The module to hide. * @param {Module} module The module to hide.
* argument speed Number - The speed of the hide animation. * @param {number} speed The speed of the hide animation.
* argument callback function - Called when the animation is done. * @param {Function} callback Called when the animation is done.
* @param {object} [options] Optional settings for the hide method.
*/ */
var hideModule = function (module, speed, callback, options) { var hideModule = function (module, speed, callback, options) {
options = options || {}; options = options || {};
@ -268,12 +270,13 @@ var MM = (function () {
} }
}; };
/* showModule(module, speed, callback) /**
* Show the module. * Show the module.
* *
* argument module Module - The module to show. * @param {Module} module The module to show.
* argument speed Number - The speed of the show animation. * @param {number} speed The speed of the show animation.
* argument callback function - Called when the animation is done. * @param {Function} callback Called when the animation is done.
* @param {object} [options] Optional settings for the show method.
*/ */
var showModule = function (module, speed, callback, options) { var showModule = function (module, speed, callback, options) {
options = options || {}; options = options || {};
@ -327,7 +330,7 @@ var MM = (function () {
} }
}; };
/* updateWrapperStates() /**
* Checks for all positions if it has visible content. * Checks for all positions if it has visible content.
* If not, if will hide the position to prevent unwanted margins. * If not, if will hide the position to prevent unwanted margins.
* This method should be called by the show and hide methods. * This method should be called by the show and hide methods.
@ -356,8 +359,8 @@ var MM = (function () {
}); });
}; };
/* loadConfig() /**
* Loads the core config and combines it with de system defaults. * Loads the core config and combines it with the system defaults.
*/ */
var loadConfig = function () { var loadConfig = function () {
// FIXME: Think about how to pass config around without breaking tests // FIXME: Think about how to pass config around without breaking tests
@ -372,41 +375,41 @@ var MM = (function () {
/* eslint-enable */ /* eslint-enable */
}; };
/* setSelectionMethodsForModules() /**
* Adds special selectors on a collection of modules. * Adds special selectors on a collection of modules.
* *
* argument modules array - Array of modules. * @param {Module[]} modules Array of modules.
*/ */
var setSelectionMethodsForModules = function (modules) { var setSelectionMethodsForModules = function (modules) {
/* withClass(className) /**
* calls modulesByClass to filter modules with the specified classes. * Filter modules with the specified classes.
* *
* argument className string/array - one or multiple classnames. (array or space divided) * @param {string|string[]} className one or multiple classnames (array or space divided).
* *
* return array - Filtered collection of modules. * @returns {Module[]} Filtered collection of modules.
*/ */
var withClass = function (className) { var withClass = function (className) {
return modulesByClass(className, true); return modulesByClass(className, true);
}; };
/* exceptWithClass(className) /**
* calls modulesByClass to filter modules without the specified classes. * Filter modules without the specified classes.
* *
* argument className string/array - one or multiple classnames. (array or space divided) * @param {string|string[]} className one or multiple classnames (array or space divided).
* *
* return array - Filtered collection of modules. * @returns {Module[]} Filtered collection of modules.
*/ */
var exceptWithClass = function (className) { var exceptWithClass = function (className) {
return modulesByClass(className, false); return modulesByClass(className, false);
}; };
/* modulesByClass(className, include) /**
* filters a collection of modules based on classname(s). * Filters a collection of modules based on classname(s).
* *
* argument className string/array - one or multiple classnames. (array or space divided) * @param {string|string[]} className one or multiple classnames (array or space divided).
* argument include boolean - if the filter should include or exclude the modules with the specific classes. * @param {boolean} include if the filter should include or exclude the modules with the specific classes.
* *
* return array - Filtered collection of modules. * @returns {Module[]} Filtered collection of modules.
*/ */
var modulesByClass = function (className, include) { var modulesByClass = function (className, include) {
var searchClasses = className; var searchClasses = className;
@ -431,12 +434,12 @@ var MM = (function () {
return newModules; return newModules;
}; };
/* exceptModule(module) /**
* Removes a module instance from the collection. * Removes a module instance from the collection.
* *
* argument module Module object - The module instance to remove from the collection. * @param {object} module The module instance to remove from the collection.
* *
* return array - Filtered collection of modules. * @returns {Module[]} Filtered collection of modules.
*/ */
var exceptModule = function (module) { var exceptModule = function (module) {
var newModules = modules.filter(function (mod) { var newModules = modules.filter(function (mod) {
@ -447,10 +450,10 @@ var MM = (function () {
return newModules; return newModules;
}; };
/* enumerate(callback) /**
* Walks thru a collection of modules and executes the callback with the module as an argument. * Walks thru a collection of modules and executes the callback with the module as an argument.
* *
* argument callback function - The function to execute with the module as an argument. * @param {Function} callback The function to execute with the module as an argument.
*/ */
var enumerate = function (callback) { var enumerate = function (callback) {
modules.map(function (module) { modules.map(function (module) {
@ -475,7 +478,7 @@ var MM = (function () {
return { return {
/* Public Methods */ /* Public Methods */
/* init() /**
* Main init method. * Main init method.
*/ */
init: function () { init: function () {
@ -488,10 +491,10 @@ var MM = (function () {
Loader.loadModules(); Loader.loadModules();
}, },
/* modulesStarted(moduleObjects) /**
* Gets called when all modules are started. * Gets called when all modules are started.
* *
* argument moduleObjects array<Module> - All module instances. * @param {Module[]} moduleObjects All module instances.
*/ */
modulesStarted: function (moduleObjects) { modulesStarted: function (moduleObjects) {
modules = []; modules = [];
@ -506,12 +509,12 @@ var MM = (function () {
createDomObjects(); createDomObjects();
}, },
/* sendNotification(notification, payload, sender) /**
* Send a notification to all modules. * Send a notification to all modules.
* *
* argument notification string - The identifier of the notification. * @param {string} notification The identifier of the notification.
* argument payload mixed - The payload of the notification. * @param {*} payload The payload of the notification.
* argument sender Module - The module that sent the notification. * @param {Module} sender The module that sent the notification.
*/ */
sendNotification: function (notification, payload, sender) { sendNotification: function (notification, payload, sender) {
if (arguments.length < 3) { if (arguments.length < 3) {
@ -533,11 +536,11 @@ var MM = (function () {
sendNotification(notification, payload, sender); sendNotification(notification, payload, sender);
}, },
/* updateDom(module, speed) /**
* Update the dom for a specific module. * Update the dom for a specific module.
* *
* argument module Module - The module that needs an update. * @param {Module} module The module that needs an update.
* argument speed Number - The number of microseconds for the animation. (optional) * @param {number} [speed] The number of microseconds for the animation.
*/ */
updateDom: function (module, speed) { updateDom: function (module, speed) {
if (!(module instanceof Module)) { if (!(module instanceof Module)) {
@ -549,36 +552,36 @@ var MM = (function () {
updateDom(module, speed); updateDom(module, speed);
}, },
/* getModules(module, speed) /**
* Returns a collection of all modules currently active. * Returns a collection of all modules currently active.
* *
* return array - A collection of all modules currently active. * @returns {Module[]} A collection of all modules currently active.
*/ */
getModules: function () { getModules: function () {
setSelectionMethodsForModules(modules); setSelectionMethodsForModules(modules);
return modules; return modules;
}, },
/* hideModule(module, speed, callback) /**
* Hide the module. * Hide the module.
* *
* argument module Module - The module hide. * @param {Module} module The module to hide.
* argument speed Number - The speed of the hide animation. * @param {number} speed The speed of the hide animation.
* argument callback function - Called when the animation is done. * @param {Function} callback Called when the animation is done.
* argument options object - Optional settings for the hide method. * @param {object} [options] Optional settings for the hide method.
*/ */
hideModule: function (module, speed, callback, options) { hideModule: function (module, speed, callback, options) {
module.hidden = true; module.hidden = true;
hideModule(module, speed, callback, options); hideModule(module, speed, callback, options);
}, },
/* showModule(module, speed, callback) /**
* Show the module. * Show the module.
* *
* argument module Module - The module show. * @param {Module} module The module to show.
* argument speed Number - The speed of the show animation. * @param {number} speed The speed of the show animation.
* argument callback function - Called when the animation is done. * @param {Function} callback Called when the animation is done.
* argument options object - Optional settings for the hide method. * @param {object} [options] Optional settings for the show method.
*/ */
showModule: function (module, speed, callback, options) { showModule: function (module, speed, callback, options) {
// do not change module.hidden yet, only if we really show it later // do not change module.hidden yet, only if we really show it later