Cleanup calendar jsdoc

modules/default/calendar/calendar.js

@@ -416,7 +416,7 @@ Module.register("calendar", {
 	 * it will a localeSpecification object with the system locale time format.
 	 *
 	 * @param {number} timeFormat Specifies either 12 or 24 hour time format
-	 * @returns {moment.LocaleSpecification}
+	 * @returns {moment.LocaleSpecification} formatted time
 	 */
 	getLocaleSpecification: function (timeFormat) {
 		switch (timeFormat) {
@@ -432,12 +432,11 @@ Module.register("calendar", {
 		}
 	},
 
-	/* hasCalendarURL(url)
-	 * Check if this config contains the calendar url.
+	/**
+	 * Checks if this config contains the calendar url.
 	 *
-	 * argument url string - Url to look for.
-	 *
-	 * return bool - Has calendar url
+	 * @param {string} url The calendar url
+	 * @returns {boolean} True if the calendar config contains the url, False otherwise
 	 */
 	hasCalendarURL: function (url) {
 		for (var c in this.config.calendars) {
@@ -450,10 +449,10 @@ Module.register("calendar", {
 		return false;
 	},
 
-	/* createEventList()
+	/**
 	 * Creates the sorted list of all events.
 	 *
-	 * return array - Array with events.
+	 * @returns {*[]} Array with events.
 	 */
 	createEventList: function () {
 		var events = [];
@@ -535,10 +534,17 @@ Module.register("calendar", {
 	},
 
 	/* createEventList(url)
-	 * Requests node helper to add calendar url.
 	 *
 	 * argument url string - Url to add.
 	 */
+
+	/**
+	 * Requests node helper to add calendar url.
+	 *
+	 * @param {string} url The calendar url to add
+	 * @param {object} auth The authentication method and credentials
+	 * @param {object} calendarConfig The config of the specific calendar
+	 */
 	addCalendar: function (url, auth, calendarConfig) {
 		this.sendSocketNotification("ADD_CALENDAR", {
 			id: this.identifier,
@@ -559,8 +565,7 @@ Module.register("calendar", {
 	 * Retrieves the symbols for a specific event.
 	 *
 	 * @param {object} event Event to look for.
-	 *
-	 * @returns {*} array The Symbols
+	 * @returns {string[]} The symbols
 	 */
 	symbolsForEvent: function (event) {
 		let symbols = this.getCalendarPropertyAsArray(event.url, "symbol", this.config.defaultSymbol);
@@ -585,82 +590,72 @@ Module.register("calendar", {
 	},
 
 	/**
-	 * symbolClassForUrl(url)
-	 * Retrieves the symbolClass for a specific url.
+	 * Retrieves the symbolClass for a specific calendar url.
 	 *
-	 * @param url string - Url to look for.
-	 *
-	 * @returns string
+	 * @param {string} url The calendar url
+	 * @returns {string} The class to be used for the symbols of the calendar
 	 */
 	symbolClassForUrl: function (url) {
 		return this.getCalendarProperty(url, "symbolClass", "");
 	},
 
 	/**
-	 * titleClassForUrl(url)
-	 * Retrieves the titleClass for a specific url.
+	 * Retrieves the titleClass for a specific calendar url.
 	 *
-	 * @param url string - Url to look for.
-	 *
-	 * @returns string
+	 * @param {string} url The calendar url
+	 * @returns {string} The class to be used for the title of the calendar
 	 */
 	titleClassForUrl: function (url) {
 		return this.getCalendarProperty(url, "titleClass", "");
 	},
 
 	/**
-	 * timeClassForUrl(url)
-	 * Retrieves the timeClass for a specific url.
+	 * Retrieves the timeClass for a specific calendar url.
 	 *
-	 * @param url string - Url to look for.
-	 *
-	 * @returns string
+	 * @param {string} url The calendar url
+	 * @returns {string} The class to be used for the time of the calendar
 	 */
 	timeClassForUrl: function (url) {
 		return this.getCalendarProperty(url, "timeClass", "");
 	},
 
-	/* calendarNameForUrl(url)
-	 * Retrieves the calendar name for a specific url.
+	/**
+	 * Retrieves the calendar name for a specific calendar url.
 	 *
-	 * argument url string - Url to look for.
-	 *
-	 * return string - The name of the calendar
+	 * @param {string} url The calendar url
+	 * @returns {string} The name of the calendar
 	 */
 	calendarNameForUrl: function (url) {
 		return this.getCalendarProperty(url, "name", "");
 	},
 
-	/* colorForUrl(url)
-	 * Retrieves the color for a specific url.
+	/**
+	 * Retrieves the color for a specific calendar url.
 	 *
-	 * argument url string - Url to look for.
-	 *
-	 * return string - The Color
+	 * @param {string} url The calendar url
+	 * @returns {string} The color
 	 */
 	colorForUrl: function (url) {
 		return this.getCalendarProperty(url, "color", "#fff");
 	},
 
-	/* countTitleForUrl(url)
-	 * Retrieves the name for a specific url.
+	/**
+	 * Retrieves the count title for a specific calendar url.
 	 *
-	 * argument url string - Url to look for.
-	 *
-	 * return string - The Symbol
+	 * @param {string} url The calendar url
+	 * @returns {string} The title
 	 */
 	countTitleForUrl: function (url) {
 		return this.getCalendarProperty(url, "repeatingCountTitle", this.config.defaultRepeatingCountTitle);
 	},
 
-	/* getCalendarProperty(url, property, defaultValue)
-	 * Helper method to retrieve the property for a specific url.
+	/**
+	 * Helper method to retrieve the property for a specific calendar url.
 	 *
-	 * argument url string - Url to look for.
-	 * argument property string - Property to look for.
-	 * argument defaultValue string - Value if property is not found.
-	 *
-	 * return string - The Property
+	 * @param {string} url The calendar url
+	 * @param {string} property The property to look for
+	 * @param {string} defaultValue The value if the property is not found
+	 * @returns {*} The property
 	 */
 	getCalendarProperty: function (url, property, defaultValue) {
 		for (var c in this.config.calendars) {
@@ -736,22 +731,27 @@ Module.register("calendar", {
 		}
 	},
 
-	/* capFirst(string)
+	/**
 	 * Capitalize the first letter of a string
-	 * Return capitalized string
+	 *
+	 * @param {string} string The string to capitalize
+	 * @returns {string} The capitalized string
 	 */
 	capFirst: function (string) {
 		return string.charAt(0).toUpperCase() + string.slice(1);
 	},
 
-	/* titleTransform(title)
+	/**
 	 * Transforms the title of an event for usage.
 	 * Replaces parts of the text as defined in config.titleReplace.
 	 * Shortens title based on config.maxTitleLength and config.wrapEvents
 	 *
-	 * argument title string - The title to transform.
-	 *
-	 * return string - The transformed title.
+	 * @param {string} title The title to transform.
+	 * @param {object} titleReplace Pairs of strings to be replaced in the title
+	 * @param {boolean} wrapEvents Wrap the text after the line has reached maxLength
+	 * @param {number} maxTitleLength The max length of the string
+	 * @param {number} maxTitleLines The max number of vertical lines before cutting event title
+	 * @returns {string} The transformed title.
 	 */
 	titleTransform: function (title, titleReplace, wrapEvents, maxTitleLength, maxTitleLines) {
 		for (var needle in titleReplace) {
@@ -770,7 +770,7 @@ Module.register("calendar", {
 		return title;
 	},
 
-	/* broadcastEvents()
+	/**
 	 * Broadcasts the events to all other modules for reuse.
 	 * The all events available in one array, sorted on startdate.
 	 */