From 1d4d5cc4e7d84cc785eca1bc3aaa8f56c3d91fb5 Mon Sep 17 00:00:00 2001 From: rejas Date: Mon, 3 Aug 2020 11:19:54 +0200 Subject: [PATCH] Cleanup calendar jsdoc --- modules/default/calendar/calendar.js | 7 +-- modules/default/calendar/calendarfetcher.js | 69 +++++++++++++-------- modules/default/calendar/node_helper.js | 13 ++-- 3 files changed, 52 insertions(+), 37 deletions(-) diff --git a/modules/default/calendar/calendar.js b/modules/default/calendar/calendar.js index c513a6f0..af804139 100755 --- a/modules/default/calendar/calendar.js +++ b/modules/default/calendar/calendar.js @@ -452,7 +452,7 @@ Module.register("calendar", { /** * Creates the sorted list of all events. * - * @returns {*[]} Array with events. + * @returns {object[]} Array with events. */ createEventList: function () { var events = []; @@ -533,11 +533,6 @@ Module.register("calendar", { return false; }, - /* createEventList(url) - * - * argument url string - Url to add. - */ - /** * Requests node helper to add calendar url. * diff --git a/modules/default/calendar/calendarfetcher.js b/modules/default/calendar/calendarfetcher.js index 888830ba..033f73cb 100644 --- a/modules/default/calendar/calendarfetcher.js +++ b/modules/default/calendar/calendarfetcher.js @@ -6,9 +6,27 @@ */ const Log = require("../../../js/logger.js"); const ical = require("ical"); -const moment = require("moment"); const request = require("request"); +/** + * Moment date + * + * @external Moment + * @see {@link http://momentjs.com} + */ +const moment = require("moment"); + +/** + * + * @param {string} url The url of the calendar to fetch + * @param {number} reloadInterval Time in ms the calendar is fetched again + * @param {string[]} excludedEvents An array of words / phrases from event titles that will be excluded from being shown. + * @param {number} maximumEntries The maximum number of events fetched. + * @param {number} maximumNumberOfDays The maximum number of days an event should be in the future. + * @param {object} auth The object containing options for authentication against the calendar. + * @param {boolean} includePastEvents If true events from the past maximumNumberOfDays will be fetched too + * @class + */ const CalendarFetcher = function (url, reloadInterval, excludedEvents, maximumEntries, maximumNumberOfDays, auth, includePastEvents) { const self = this; @@ -18,7 +36,7 @@ const CalendarFetcher = function (url, reloadInterval, excludedEvents, maximumEn let fetchFailedCallback = function () {}; let eventsReceivedCallback = function () {}; - /* fetchCalendar() + /** * Initiates calendar fetch. */ const fetchCalendar = function () { @@ -325,7 +343,7 @@ const CalendarFetcher = function (url, reloadInterval, excludedEvents, maximumEn }); }; - /* scheduleTimer() + /** * Schedule the timer for the next update. */ const scheduleTimer = function () { @@ -335,12 +353,11 @@ const CalendarFetcher = function (url, reloadInterval, excludedEvents, maximumEn }, reloadInterval); }; - /* isFullDayEvent(event) + /** * Checks if an event is a fullday event. * - * argument event object - The event object to check. - * - * return bool - The event is a fullday event. + * @param {object} event The event object to check. + * @returns {boolean} True if the event is a fullday event, false otherwise */ const isFullDayEvent = function (event) { if (event.start.length === 8 || event.start.dateOnly) { @@ -358,14 +375,13 @@ const CalendarFetcher = function (url, reloadInterval, excludedEvents, maximumEn return false; }; - /* timeFilterApplies() + /** * Determines if the user defined time filter should apply * - * argument now Date - Date object using previously created object for consistency - * argument endDate Moment - Moment object representing the event end date - * argument filter string - The time to subtract from the end date to determine if an event should be shown - * - * return bool - The event should be filtered out + * @param {Date} now Date object using previously created object for consistency + * @param {Moment} endDate Moment object representing the event end date + * @param {string} filter The time to subtract from the end date to determine if an event should be shown + * @returns {boolean} True if the event should be filtered out, false otherwise */ const timeFilterApplies = function (now, endDate, filter) { if (filter) { @@ -380,12 +396,11 @@ const CalendarFetcher = function (url, reloadInterval, excludedEvents, maximumEn return false; }; - /* getTitleFromEvent(event) + /** * Gets the title from the event. * - * argument event object - The event object to check. - * - * return string - The title of the event, or "Event" if no title is found. + * @param {object} event The event object to check. + * @returns {string} The title of the event, or "Event" if no title is found. */ const getTitleFromEvent = function (event) { let title = "Event"; @@ -416,14 +431,14 @@ const CalendarFetcher = function (url, reloadInterval, excludedEvents, maximumEn /* public methods */ - /* startFetch() + /** * Initiate fetchCalendar(); */ this.startFetch = function () { fetchCalendar(); }; - /* broadcastItems() + /** * Broadcast the existing events. */ this.broadcastEvents = function () { @@ -431,37 +446,37 @@ const CalendarFetcher = function (url, reloadInterval, excludedEvents, maximumEn eventsReceivedCallback(self); }; - /* onReceive(callback) + /** * Sets the on success callback * - * argument callback function - The on success callback. + * @param {Function} callback The on success callback. */ this.onReceive = function (callback) { eventsReceivedCallback = callback; }; - /* onError(callback) + /** * Sets the on error callback * - * argument callback function - The on error callback. + * @param {Function} callback The on error callback. */ this.onError = function (callback) { fetchFailedCallback = callback; }; - /* url() + /** * Returns the url of this fetcher. * - * return string - The url of this fetcher. + * @returns {string} The url of this fetcher. */ this.url = function () { return url; }; - /* events() + /** * Returns current available events for this fetcher. * - * return array - The current available events for this fetcher. + * @returns {object[]} The current available events for this fetcher. */ this.events = function () { return events; diff --git a/modules/default/calendar/node_helper.js b/modules/default/calendar/node_helper.js index e731ca6c..862755a0 100644 --- a/modules/default/calendar/node_helper.js +++ b/modules/default/calendar/node_helper.js @@ -4,7 +4,6 @@ * By Michael Teeuw https://michaelteeuw.nl * MIT Licensed. */ - const NodeHelper = require("node_helper"); const validUrl = require("valid-url"); const CalendarFetcher = require("./calendarfetcher.js"); @@ -24,12 +23,18 @@ module.exports = NodeHelper.create({ } }, - /* createFetcher(url, reloadInterval) + /** * Creates a fetcher for a new url if it doesn't exist yet. * Otherwise it reuses the existing one. * - * attribute url string - URL of the news feed. - * attribute reloadInterval number - Reload interval in milliseconds. + * @param {string} url The url of the calendar + * @param {number} fetchInterval How often does the calendar needs to be fetched in ms + * @param {string[]} excludedEvents An array of words / phrases from event titles that will be excluded from being shown. + * @param {number} maximumEntries The maximum number of events fetched. + * @param {number} maximumNumberOfDays The maximum number of days an event should be in the future. + * @param {object} auth The object containing options for authentication against the calendar. + * @param {boolean} broadcastPastEvents If true events from the past maximumNumberOfDays will be included in event broadcasts + * @param {string} identifier ID of the module */ createFetcher: function (url, fetchInterval, excludedEvents, maximumEntries, maximumNumberOfDays, auth, broadcastPastEvents, identifier) { var self = this;