add jsdoc

eslint.config.mjs

@@ -29,7 +29,7 @@ export default [
             "@typescript-eslint/no-unused-vars": "warn",
             "prettier/prettier": "warn",
             "no-debugger": "warn",
-            'jsdoc/require-jsdoc': 'off',
+            'jsdoc/require-jsdoc': 'warn',
         },
     },
 

lib/ioUtil.js

@@ -167,6 +167,14 @@ class ioUtil {
         const name = (level1path ? `${level1path}.` : '') + (level2path ? `${level2path}.` : '') + id;
         this.adapter.getState(name, callback);
     }
+    /**
+     * Asynchronously retrieves the state of an object in the ioBroker system.
+     *
+     * @param id - The name of the state to retrieve.
+     * @param level1path - The first level path to prepend to the state name, can be null or empty.
+     * @param level2path - The second level path to prepend to the state name, can be null or empty.
+     * @returns A promise that resolves with the state object.
+     */
     async getStateAsync(id, level1path, level2path) {
         this.logdebug(`getStateAsync ${id}`);
         const name = (level1path ? `${level1path}.` : '') + (level2path ? `${level2path}.` : '') + id;
@@ -295,6 +303,12 @@ class ioUtil {
     loginfo(s) {
         this.adapter.log.info(s);
     }
+    /**
+     * Delays execution for a specified number of milliseconds.
+     *
+     * @param ms - The number of milliseconds to delay execution.
+     * @returns A promise that resolves after the specified delay.
+     */
     async delay(ms) {
         return new Promise(resolve => setTimeout(resolve, ms));
     }

lib/ski/SkiArea.js

@@ -1,11 +1,30 @@
 const cheerio = require('cheerio');
 const SkiConfig = require('./SkiConfig');
 module.exports = class SkiArea {
+    /**
+     * Create a new instance of the SkiArea class.
+     *
+     * @param country - The country where the area is located.
+     *
+     * This constructor sets the country and region properties of the new instance.
+     * The region is set to null, and the isFavorite property is set to false.
+     */
     constructor(country) {
         this.country = country;
         this.region = null;
         this.isFavorite = false;
     }
+    /**
+     * Parse the given HTML element and extract the area's details.
+     *
+     * @param el - The HTML element to parse.
+     *
+     * This function sets the area's code, name, url, snow depths (valley and mountain),
+     * fresh snow, open and all lifts, and the last update time.
+     *
+     * If the country has regions, the function tries to find the region that the area
+     * belongs to and sets the area's region property accordingly.
+     */
     parse(el) {
         const regex = /\/(.+)\/sch/;
         const $ = cheerio.load(el);
@@ -38,9 +57,32 @@ module.exports = class SkiArea {
             }
         }
     }
+    /**
+     * Sets the region code for this area.
+     *
+     * @param region - The code of the region to associate with this area.
+     */
     setRegion(region) {
         this.region = region;
     }
+    /**
+     * Returns an object representation of the ski area with various details.
+     *
+     * @param country - The code of the country this ski area belongs to.
+     * @returns An object containing the ski area's properties, including:
+     *                   - name: The name of the ski area.
+     *                   - code: The unique code of the ski area.
+     *                   - url: The URL to the ski area's page.
+     *                   - isFavorite: Boolean indicating if this area is a favorite.
+     *                   - country: The code of the country.
+     *                   - region: The code of the region, or null if not set.
+     *                   - snowValley: Snow depth in the valley.
+     *                   - snowMountain: Snow depth on the mountain.
+     *                   - freshSnow: Amount of fresh snow.
+     *                   - liftsOpen: Number of lifts currently open.
+     *                   - liftsAll: Total number of lifts.
+     *                   - lastUpdate: The last update timestamp.
+     */
     getObject(country) {
         return {
             name: this.name,

lib/ski/SkiCache.js

@@ -1,6 +1,11 @@
 module.exports = class SkiCache {
     data = [];
-    /*     constructor(parameters) { } */
+
+    /**
+     * Returns the cached data.
+     *
+     * @returns The cached data.
+     */
     getData() {
         return this.data;
     }

lib/ski/SkiConfig.js

@@ -1,13 +1,27 @@
 module.exports = class SkiConfig {
     static priv_baseurl = 'https://www.bergfex.ch';
     static priv_delaytime = 2 * 60 * 1000; //2 minutes
-    /*     constructor() { } */
+
+    /**
+     * Base URL of the website to scrape
+     *
+     */
     static get baseurl() {
         return 'https://www.bergfex.ch';
     }
+    /**
+     * Gets the delay time used between requests.
+     *
+     * @returns The delay time in milliseconds.
+     */
     static get delaytime() {
         return 2 * 1000; //2 seconds
     }
+    /**
+     * The time in milliseconds that the cache is valid.
+     *
+     * @returns The cache time in milliseconds.
+     */
     static get cachetime() {
         return 60 * 60 * 1000; //1 hour
     }

lib/ski/SkiCountry.js

@@ -3,6 +3,15 @@ const SkiConfig = require('./SkiConfig');
 const SkiRegion = require('./SkiRegion');
 const SkiArea = require('./SkiArea');
 module.exports = class SkiCountry {
+    /**
+     * Create a new instance of the SkiCountry class.
+     *
+     * @param util - The SkiUtil instance used for utility functions.
+     *
+     * The constructor initializes the SkiCountry instance by setting up the
+     * util property and the state properties, which are name, code, url,
+     * regions, areas and loaded.
+     */
     constructor(util) {
         this.util = util;
         this.name = null;
@@ -12,6 +21,13 @@ module.exports = class SkiCountry {
         this.areas = [];
         this.loaded = false;
     }
+    /**
+     * Parse the given HTML element and extract the country's details.
+     *
+     * @param el - The HTML element to parse.
+     *
+     * This function sets the country's code, name, and URL.
+     */
     parseCountry(el) {
         const regex = /\/(.+)\/sch/;
         const $ = cheerio.load(el);
@@ -23,6 +39,15 @@ module.exports = class SkiCountry {
         this.name = $(el).text();
         this.url = SkiConfig.baseurl + $(el).attr('href');
     }
+    /**
+     * Parse the given HTML and extract the country's regions.
+     *
+     * @param html - The HTML to parse.
+     *
+     * This function sets the country's regions property with an array of SkiRegion
+     * objects. The function only parses the first region and loads its data.
+     * The other regions are created but their data is not loaded yet.
+     */
     async parseRegions(html) {
         this.regions = [];
         const $ = cheerio.load(html);
@@ -38,6 +63,17 @@ module.exports = class SkiCountry {
         }
         //});
     }
+    /**
+     * Parse the given HTML and extract the ski area's details.
+     *
+     * @param html - The HTML to parse.
+     *
+     * This function initializes the areas array and populates it with SkiArea
+     * objects by parsing the specified HTML. Each SkiArea object is created
+     * by parsing individual elements that match the '.snow .tr0' and '.snow .tr1'
+     * selectors within the provided HTML. The function does not load additional
+     * data for each area at this stage.
+     */
     parseAreas(html) {
         this.areas = [];
         const $ = cheerio.load(html);
@@ -50,6 +86,13 @@ module.exports = class SkiCountry {
             //});
         }
     }
+    /**
+     * Loads the country data if it was not already loaded.
+     *
+     * If the country's URL is set, the function requests the HTML from the
+     * specified URL, parses the regions and areas, and sets the loaded property
+     * to true.
+     */
     async load() {
         if (this.url) {
             let html = await this.util.request(this.url);
@@ -58,24 +101,69 @@ module.exports = class SkiCountry {
             this.loaded = true;
         }
     }
+    /**
+     * Returns an array of all the regions of this country.
+     *
+     * @returns The array of SkiRegion objects.
+     */
     getRegions() {
         return this.regions;
     }
+    /**
+     * Retrieves a region by its name.
+     *
+     * @param name - The name of the region to find.
+     * @returns The SkiRegion object with the matching name, or undefined if not found.
+     */
     getRegionByName(name) {
         return this.regions.find(el => el.name == name);
     }
+    /**
+     * Retrieves a region by its code.
+     *
+     * @param code - The code of the region to find.
+     * @returns The SkiRegion object with the matching code, or undefined if not found.
+     */
     getRegionByCode(code) {
         return this.regions.find(el => el.code == code);
     }
+    /**
+     * Returns an array of all the ski areas of this country.
+     *
+     * @returns The array of SkiArea objects.
+     */
     getAreas() {
         return this.areas;
     }
+    /**
+     * Retrieves a ski area by its name.
+     *
+     * @param name - The name of the ski area to find.
+     * @returns The SkiArea object with the matching name, or undefined if not found.
+     */
     getAreaByName(name) {
         return this.areas.find(el => el.name == name);
     }
+    /**
+     * Retrieves a ski area by its code.
+     *
+     * @param code - The code of the ski area to find.
+     * @returns The SkiArea object with the matching code, or undefined if not found.
+     */
     getAreaByCode(code) {
         return this.areas.find(el => el.code == code);
     }
+    /**
+     * Returns an object representation of the country with various details.
+     *
+     * @returns An object containing the country's properties, including:
+     *                   - name: The name of the country.
+     *                   - code: The unique code of the country.
+     *                   - url: The URL to the country's page.
+     *                   - regions: An array of SkiRegion objects.
+     *                   - areas: An array of SkiArea objects.
+     *                   - loaded: Boolean indicating if the country has been loaded.
+     */
     getObject() {
         return {
             name: this.name,
@@ -86,6 +174,11 @@ module.exports = class SkiCountry {
             loaded: this.loaded,
         };
     }
+    /**
+     * Returns true if any ski area of this country is a favorite.
+     *
+     * @returns Boolean indicating if the country contains any favorite ski areas.
+     */
     containFavoriteAreas() {
         return this.areas.some(area => area.isFavorite);
     }

lib/ski/SkiCountryList.js

@@ -5,15 +5,40 @@ const SkiCountry = require('./SkiCountry');
 module.exports = class BerfexCountryList {
     countries = [];
 
+    /**
+     * The constructor for the class.
+     *
+     * @param util - An instance of the SkiUtil class, used for
+     *                         making web requests.
+     */
     constructor(util) {
         this.config = new SkiConfig();
         this.util = util;
     }
+    /**
+     * Loads the list of countries from the bergfex.ch website.
+     *
+     * This function requests the HTML from the bergfex.ch website and then
+     * calls the parse method to extract the country data from the HTML.
+     *
+     * @returns A promise that resolves when the loading and parsing of the
+     *          country data is complete.
+     */
     async load() {
         let url = `${SkiConfig.baseurl}/schweiz/schneewerte/`;
         let html = await this.util.request(url);
         await this.parse(html);
     }
+    /**
+     * Parses the HTML and extracts the country data.
+     *
+     * This function takes the HTML string and parses it using the cheerio library.
+     * It then extracts the country data from the HTML and stores it in the
+     * countries array.
+     *
+     * @param html - The HTML string to parse.
+     * @returns A promise that resolves when the parsing is complete.
+     */
     async parse(html) {
         /*         const regex = /\/(.+)\/sch/; */
         const $ = cheerio.load(html);
@@ -27,18 +52,52 @@ module.exports = class BerfexCountryList {
         let curCountry = this.getCountryByName(curCountryText);
         await curCountry.load();
     }
+    /**
+     * Returns the list of countries.
+     *
+     * @returns An array of SkiCountry objects, each one representing a country.
+     */
     getCountries() {
         return this.countries;
     }
+    /**
+     * Finds a country by its name.
+     *
+     * @param name - The name of the country to find.
+     * @returns The SkiCountry object with the matching name, or undefined if not found.
+     */
     getCountryByName(name) {
         return this.countries.find(el => el.name == name);
     }
+    /**
+     * Finds a country by its code.
+     *
+     * @param code - The code of the country to find.
+     * @returns The SkiCountry object with the matching code, or undefined if not found.
+     */
     getCountryByCode(code) {
         return this.countries.find(el => el.code == code);
     }
+    /**
+     * Returns an object representation of the country list with various details.
+     *
+     * @returns An array of objects, each one representing a country, with the following properties:
+     *                   - name: The name of the country.
+     *                   - code: The unique code of the country.
+     *                   - url: The URL to the country's page.
+     *                   - regions: An array of SkiRegion objects.
+     *                   - areas: An array of SkiArea objects.
+     *                   - loaded: Boolean indicating if the country has been loaded.
+     */
     getObject() {
         return this.countries.map(country => country.getObject());
     }
+    /**
+     * Returns an array of countries that contain at least one favorite ski area.
+     *
+     * @returns An array of SkiCountry objects, each one representing a country
+     *          that contains at least one favorite ski area.
+     */
     getCountriesOfFavorties() {
         return this.countries.filter(country => country.containFavoriteAreas());
     }