JS Docs

assets/src/modules/Errors.js

@@ -1,6 +1,20 @@
+/**
+ * @module Errors.js
+ * @copyright 2023 3Liz
+ * @author DHONT René-Luc
+ * @license MPL-2.0 - Mozilla Public License 2.0 : http://www.mozilla.org/MPL/
+ **/
+
+/**
+ * Representing an HTTP error with message and status code
+ * @class
+ * @augments Error
+ **/
 class HttpError extends Error {
 
     /**
+     * Creating an HTTP error with message and status code
+     *
      * @param {String} message - Error message
      * @param {int}    statusCode - HTTP Error status code
      */
@@ -11,9 +25,17 @@ class HttpError extends Error {
     }
 }
 
+/**
+ * Representing a conversion error
+ *
+ * @class
+ * @augments Error
+ **/
 class ConversionError extends Error {
 
     /**
+     * Creating a conversion error
+     *
      * @param {String} message - Error message
      */
     constructor(message) {
@@ -23,9 +45,17 @@ class ConversionError extends Error {
 
 }
 
+/**
+ * Representing a validation error
+ *
+ * @class
+ * @augments Error
+ **/
 class ValidationError extends Error {
 
     /**
+     * Creating a validation error
+     *
      * @param {String} message - Error message
      */
     constructor(message) {
@@ -35,6 +65,12 @@ class ValidationError extends Error {
 
 }
 
+/**
+ * Representing a property required error
+ *
+ * @class
+ * @augments ValidationError
+ **/
 class PropertyRequiredError extends ValidationError {
 
     /**

assets/src/modules/config/Layer.js

@@ -1,3 +1,10 @@
+/**
+ * @module config/Layer.js
+ * @copyright 2023 3Liz
+ * @author DHONT René-Luc
+ * @license MPL-2.0 - Mozilla Public License 2.0 : http://www.mozilla.org/MPL/
+ **/
+
 import { BaseObjectConfig } from './BaseObject.js';
 import { ValidationError } from './../Errors.js';
 
@@ -86,7 +93,7 @@ export class LayerConfig extends BaseObjectConfig {
     }
 
     /**
-     * The layer id
+     * The layer id - QGIS layer id
      *
      * @type {String}
      **/
@@ -95,7 +102,7 @@ export class LayerConfig extends BaseObjectConfig {
     }
 
     /**
-     * The layer name
+     * The layer name - QGIS layer name
      *
      * @type {String}
      **/
@@ -113,7 +120,7 @@ export class LayerConfig extends BaseObjectConfig {
     }
 
     /**
-     * The layer short name
+     * The layer short name - will be the WMS/WFS/WMTS name if not null
      *
      * @type {?String}
      **/
@@ -377,13 +384,14 @@ export class LayerConfig extends BaseObjectConfig {
 }
 
 /**
- * Class representing a layers config
+ * Class representing the layers config accessor
  * @class
  */
 export class LayersConfig {
 
     /**
-     * Create a layers config instance based on a config object
+     * Create a layers config accessor instance based on a config object
+     *
      * @param {Object} cfg - the lizmap config object for layers
      */
     constructor(cfg) {

assets/src/modules/config/LayerTree.js

@@ -1,10 +1,16 @@
 import { Extent } from './../utils/Extent.js';
 import { AttributionConfig } from './Attribution.js';
 
+/**
+ * Class representing a wMS layer Geographic Bounding Box
+ * @class
+ * @augments Extent
+ */
 export class LayerGeographicBoundingBoxConfig extends Extent {
 
     /**
-     * Create the wms layer Geographic Bounding Box
+     * Create the WMS layer Geographic Bounding Box
+     *
      * @param {...Number} args - the 4 values describing the Geographic Bounding Box: west, south, east, north
      *
      * @throws {ValidationError} for number of args different of 4
@@ -43,6 +49,11 @@ export class LayerGeographicBoundingBoxConfig extends Extent {
     }
 }
 
+/**
+ * Class representing a layer bounding box config
+ * @class
+ * @augments Extent
+ */
 export class LayerBoundingBoxConfig extends Extent {
     /**
      * Create the wms layer Geographic Bounding Box
@@ -67,10 +78,15 @@ export class LayerBoundingBoxConfig extends Extent {
     }
 }
 
-
+/**
+ * Class representing a layer style config
+ * @class
+ */
 export class LayerStyleConfig {
 
     /**
+     * Create a layer style config
+     *
      * @param {String} wmsName  - the layer wms style name
      * @param {String} wmsTitle - the layer wms style title
      */
@@ -102,9 +118,15 @@ export class LayerStyleConfig {
 
 }
 
+/**
+ * Class representing a layer tree item config
+ * @class
+ */
 export class LayerTreeItemConfig {
 
     /**
+     * Create a layer tree item config instance
+     *
      * @param {String}      name         - the QGIS layer name
      * @param {String}      type         - the layer tree item type
      * @param {Number}      level        - the layer tree item level
@@ -124,7 +146,7 @@ export class LayerTreeItemConfig {
     }
 
     /**
-     * QGIS layer name
+     * The layer name - QGIS layer name
      *
      * @type {String}
      **/
@@ -244,9 +266,16 @@ export class LayerTreeItemConfig {
     }
 }
 
+/**
+ * Class representing a layer tree layer config
+ * @class
+ * @augments LayerTreeItemConfig
+ */
 export class LayerTreeLayerConfig extends LayerTreeItemConfig {
 
     /**
+     * Create a layer tree layer config instance
+     *
      * @param {String}      name         - the QGIS layer name
      * @param {Number}      level        - the layer tree item level
      * @param {Object}      wmsCapaLayer - the WMS capabilities layer element
@@ -289,9 +318,16 @@ export class LayerTreeLayerConfig extends LayerTreeItemConfig {
     }
 }
 
+/**
+ * Class representing a layer tree group config
+ * @class
+ * @augments LayerTreeItemConfig
+ */
 export class LayerTreeGroupConfig extends LayerTreeItemConfig {
 
     /**
+     * Create a layer tree group config instance
+     *
      * @param {String}                name         - the QGIS layer name
      * @param {Number}                level        - the layer tree item level
      * @param {LayerTreeItemConfig[]} items        - the children layer tree items
@@ -370,10 +406,14 @@ export class LayerTreeGroupConfig extends LayerTreeItemConfig {
 }
 
 /**
+ * Function to build layer tree items config based on WMS capabilities
+ * @function
+ *
  * @param {Object}       wmsCapaLayerGroup - the wms layer capabilities
  * @param {LayersConfig} layersCfg         - the lizmap layers config instance
+ * @param {Number}       level             - the wms layer level
  *
- * @returns {LayerTreeItemConfig[]}
+ * @returns {LayerTreeItemConfig[]} the layer tree items of the wms layer
  */
 function buildLayerTreeGroupConfigItems(wmsCapaLayerGroup, layersCfg, level) {
     let items = [];
@@ -397,12 +437,13 @@ function buildLayerTreeGroupConfigItems(wmsCapaLayerGroup, layersCfg, level) {
 }
 
 /**
- * Building the layer tree config based on WMS capabilities
+ * Function to build the root layer tree config based on WMS capabilities
+ * @function
  *
  * @param {Object}       wmsCapaLayerRoot - the wms root layer capabilities
  * @param {LayersConfig} layersCfg        - the lizmap layers config instance
  *
- * @returns {LayerTreeGroupConfig}
+ * @returns {LayerTreeGroupConfig} The root layer tree config based on WMS capabilities
  */
 export function buildLayerTreeConfig(wmsCapaLayerRoot, layersCfg) {
     let items = buildLayerTreeGroupConfigItems(wmsCapaLayerRoot, layersCfg, 0);

assets/src/modules/config/LayersOrder.js

@@ -1,3 +1,19 @@
+/**
+ * @module config/LayersOrder.js
+ * @copyright 2023 3Liz
+ * @author DHONT René-Luc
+ * @license MPL-2.0 - Mozilla Public License 2.0 : http://www.mozilla.org/MPL/
+ **/
+
+/**
+ * Recursive function to build the layer names displaying order like in QGIS based on the layer tree
+ * config group from WMS capabilities
+ * @function
+ *
+ * @param {LayerTreeGroupConfig} layerTreeGroupCfg - The layer tree config based on WMS capabilities
+ *
+ * @return {String[]} The layer names list from top to bottom
+ **/
 function layersOrderFromLayerTreeGroup(layerTreeGroupCfg) {
     let layersOrder = [];
     for (const layerTreeItem of layerTreeGroupCfg.getChildren()) {
@@ -16,6 +32,19 @@ function layersOrderFromLayerTreeGroup(layerTreeGroupCfg) {
     return layersOrder;
 }
 
+/**
+ * Function to build the layer names displaying order like in QGIS based on lizmap config
+ * or the layer tree config based on WMS capabilities
+ *
+ * The first one in this list is the top one in the map
+ * The last one in this list is the bottom one in the map
+ * @function
+ *
+ * @param {Object} initialConfig
+ * @param {LayerTreeGroupConfig} rootLayerTreeCfg - The root layer tree config based on WMS capabilities
+ *
+ * @return {String[]} The layer names displaying order from top to bottom
+ **/
 export function buildLayersOrder(initialConfig, rootLayerTreeCfg) {
     if (initialConfig.hasOwnProperty('layersOrder')) {
         return Object.keys(initialConfig.layersOrder).sort(function(a, b) {

assets/src/modules/utils/Converters.js

@@ -1,7 +1,15 @@
+/**
+ * @module utils/Converters.js
+ * @copyright 2023 3Liz
+ * @author DHONT René-Luc
+ * @license MPL-2.0 - Mozilla Public License 2.0 : http://www.mozilla.org/MPL/
+ **/
+
 import { ConversionError } from './../Errors.js';
 
 /**
  * Convert a value to Number
+ * @function
  *
  * @param {*} val - A value to convert to number
  *
@@ -19,6 +27,7 @@ export function convertNumber(val) {
 
 /**
  * Convert a value to boolean
+ * @function
  *
  * @param {*} val - A value to convert to boolean
  *
@@ -72,10 +81,11 @@ export function convertBoolean(val) {
  * of the given string, n is the length of the string,
  * and ^ indicates exponentiation.
  * (The hash value of the empty string is zero.)
+ * @function
  *
- * @param {string} s a string
+ * @param {string} s - A string
  * @return {number} a hash code value for the given string.
- */
+ **/
 export function hashCode(s) {
     let h = 0;
     for(let i = 0; i < s.length; i++) {

assets/src/modules/utils/Extent.js

@@ -1,3 +1,10 @@
+/**
+ * @module utils/Extent.js
+ * @copyright 2023 3Liz
+ * @author DHONT René-Luc
+ * @license MPL-2.0 - Mozilla Public License 2.0 : http://www.mozilla.org/MPL/
+ **/
+
 import { ValidationError } from './../Errors.js';
 import { convertNumber } from './Converters.js';
 
@@ -56,6 +63,13 @@ export class Extent extends Array {
         return this[3];
     }
 
+    /**
+     * Checks equality with an other extent or array
+     *
+     * @param {Extent|Array} anOther - An other extent or array with 4 values
+     *
+     * @return {Boolean} the other extent or array as the same values
+     **/
     equals(anOther) {
         return ( anOther instanceof Array
             && anOther.length == 4