Fix #10778 Dev guide, JSDoc and migration documentation for the new homepage plugins

package.json

@@ -310,9 +310,11 @@
     "doc": "npm run jsdoc:build",
     "cleandoc": "npm run jsdoc:clean",
     "doctest": "npm run jsdoc:test",
-    "jsdoc:build": "docma -c build/docma-config.json --dest web/docs",
+    "jsdoc:build": "npm run jsdoc:check && docma -c build/docma-config.json --dest web/docs",
     "jsdoc:clean": "rimraf web/docs && rimraf web/client/mapstore/docs",
     "jsdoc:test": "docma -c build/docma-config.json --dest web/client/mapstore/docs && echo documentation is accessible from the mapstore/docs path when running npm start",
+    "jsdoc:check": "node ./utility/doc/jsDocConfigCheck.js",
+    "jsdoc:update": "node ./utility/doc/jsDocConfigUpdate.js",
     "doc:build": "mkdocs build",
     "doc:start": "mkdocs serve",
     "postinstall": "node utility/build/postInstall.js",

utility/doc/jsDocConfigCheck.js

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2025, GeoSolutions Sas.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const utils = require('./jsDocUtils');
+
+const src = utils.parseSections(utils.defaultSections);
+const config = utils.getConfig();
+
+const currentSrc = config.src[0];
+
+const keys = ['jsapi', 'plugins'];
+
+let failMessage = '';
+
+keys.forEach(key  => {
+    const missing = src[key].filter((file) => !currentSrc[key].includes(file));
+    if (missing.length) {
+        failMessage = `${failMessage}${missing.map(file => `  docma-config.json: missing entry in src[0].${key} ${file}`).join('\n')}\n`;
+    }
+    const wrong = currentSrc[key].filter((file) => !src[key].includes(file));
+    if (wrong.length) {
+        failMessage = `${failMessage}${wrong.map(file => `  docma-config.json: wrong entry in src[0].${key} ${file}`).join('\n')}\n`;
+    }
+});
+
+if (failMessage) {
+    throw Error(`jsdoc check failure caused by:\n\n${failMessage}\n\nuse following command to update docma-config.json file:\n\n  npm run jsdoc:update\n\n---------\n\n`);
+}

utility/doc/jsDocConfigUpdate.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2025, GeoSolutions Sas.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const utils = require('./jsDocUtils');
+
+const src = utils.parseSections(utils.defaultSections);
+
+utils.updateConfig((config) => {
+    return {
+        ...config,
+        src: [
+            {
+                ...config.src[0],
+                jsapi: src.jsapi,
+                plugins: src.plugins
+            }
+        ]
+    };
+});

utility/doc/jsDocUtils.js

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2025, GeoSolutions Sas.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function checkFolder(dirPath, check) {
+    const entries = fs.readdirSync(dirPath);
+    const indexPath = path.join(dirPath, 'index.jsdoc');
+    return [
+        ...(fs.existsSync(indexPath) ? [indexPath.split('\\').join('/')] : []),
+        ...entries.map(entry => {
+            if (entry === '__tests__') {
+                return null;
+            }
+            const entryPath = path.join(dirPath, entry);
+            const stats = fs.lstatSync(entryPath);
+            if (stats.isDirectory()) {
+                return checkFolder(entryPath, check);
+            }
+            const content = fs.readFileSync(entryPath, 'utf8');
+            if (check(content)) {
+                return entryPath.split('\\').join('/');
+            }
+            return null;
+        }).filter(val => val).flat()
+    ];
+}
+
+const defaultSections = {
+    framework: {
+        path: 'web/client',
+        check: content => content.includes('@memberof')
+            && !content.includes('@memberof plugins')
+            && !content.includes('@memberof MapStore2')
+    },
+    jsapi: {
+        path: 'web/client/jsapi',
+        check: content => content.includes('@memberof MapStore2')
+    },
+    plugins: {
+        path: 'web/client/plugins',
+        check: content => content.includes('@memberof plugins')
+    }
+};
+
+const configPath = 'build/docma-config.json';
+const getConfig = () => JSON.parse(fs.readFileSync('build/docma-config.json', 'utf-8'));
+
+module.exports = {
+    getConfig,
+    updateConfig: (updateFunc) => {
+        const config = getConfig();
+        fs.writeFileSync(configPath, JSON.stringify(updateFunc(config), null, 4));
+    },
+    defaultSections,
+    parseSections: (sections) => {
+        return Object.fromEntries(Object.keys(sections).map((key) => {
+            const options =  sections[key];
+            return [key, checkFolder(path.join(options.path), options.check)];
+        }));
+    }
+};

web/client/actions/catalog.js

@@ -188,7 +188,6 @@ export function addCatalogService(service) {
 /**
  *
  * @param {object[]} services list of services to full replace catalog ones
- * @returns
  */
 export function updateCatalogServices(services) {
     return {

web/client/actions/featuregrid.js

@@ -178,7 +178,6 @@ export function toggleSelection(features) {
  * @memberof actions.featuregrid
  * @param {boolean} [options.multiselect] if true, allows multiple feature selection
  * @param {boolean} [showCheckbox] allow to show/hide checkboxes.
- * @returns
  */
 export function setSelectionOptions({multiselect, showCheckbox} = {}) {
     return {

web/client/actions/layers.js

@@ -41,7 +41,6 @@ export const REPLACE_LAYERS = 'LAYERS:REPLACE_LAYERS';
 /**
  * full replacement of layers in layers state
  * @param {object[]} layers the new layers to replace in the state
- * @returns
  */
 export function replaceLayers(layers) {
     return {

web/client/actions/timeline.js

@@ -32,15 +32,15 @@ export const UPDATE_TIME_LAYERS_SETTINGS = "TIMELINE:UPDATE_LAYERS_SETTINGS";
  * @param {string} group the group of the selected time (typically the layer name)
  * @param {string} [what] clicked element. Can be 'timeline' or others
  * @param {object} [item] the effective clicked item, if any
- * @return object of type `TIMELINE:SELECT_TIME` with `time` group` `what` `item`
+ * @return {object} object of type `TIMELINE:SELECT_TIME` with `time` group` `what` `item`
  */
 export const selectTime = (time, group, what, item) => ({ type: SELECT_TIME, time, group, what, item});
 
 /**
  * Action creator for time range change event
  * @memberof actions.timeline
  * @param {object} param0 start/end object
- * @return action of type `RANGE_CHANGED` with start and end.
+ * @return {object} action of type `RANGE_CHANGED` with start and end.
  */
 export const onRangeChanged = ({start, end} = {}) => ({type: RANGE_CHANGED, start, end});
 

web/client/actions/wfsquery.js

@@ -115,7 +115,6 @@ export function queryError(error) {
  * @param {object} [param.updates] updates to apply to the filter object (merged with the original filter)
  * @param {string} [param.reason] "geometry" or undefined. If "geometry", triggers selection of features.
  * @param {boolean} [param.useLayerFilter] enable/disable the usage of the current layer filter
- * @returns
  */
 export function updateQuery({updates, reason, useLayerFilter} = {}) {
     return {

web/client/api/MultiDim.js

@@ -31,7 +31,7 @@ export const trimUndefinedParams = o =>
  * @param {string} layer the layer name
  * @param {object} dimensionIdentifiers At most one per dimension, a range described as min/max, restricting the domain of this dimension
  * @param {object} options params of the request.
- * @returns a stream that emits the request result
+ * @returns {*} a stream that emits the request result
  */
 export const describeDomains = (url, layer, dimensionIdentifiers = {}, {
     service = "WMTS",

web/client/api/WFS.js

@@ -88,7 +88,6 @@ export const getFeatureURL = (url, typeName, { version = "1.1.0", ...params } =
  * - `outputFormat`: output format string. Default: `application/json`
  * - `resultType`: result type string. Default: `results`
  * @param {object} config axios request config (headers, etc...)
- * @returns
  */
 export const getFeatureLayer = (layer, {version =  "1.1.0", filters, proj, outputFormat = 'application/json', resultType = 'results'} = {}, config) => {
     const {url, name: typeName, params } = layer;

web/client/components/contextcreator/ConfigureThemes.jsx

@@ -37,7 +37,6 @@ const SUCCESS = "ms-success";
  * @param {object} defaultVars variables of the theme used to initialize the pickers
  * @param {object} basic variables to use if a theme is not selected
  * @param {string} varName variable name to be use for comparison
- * @returns
  */
 const hasColorChanged = (vars, defaultVars, basic, varName) => {
     return !tinycolor.equals(vars?.[varName], defaultVars?.[varName] || basic[varName]);
@@ -49,7 +48,6 @@ const hasColorChanged = (vars, defaultVars, basic, varName) => {
  * @param {object} basicVariables the variables used as default values if a theme is not selected
  * @param {object[]} themes the list of themes to show in the selector field
  * @param {boolean} customVariablesEnabled flag to enabled/disable the custom variables section
- * @returns
  */
 function ConfigureThemes({
     themes = [],

web/client/components/map/enhancers/withScalesDenominators.js

@@ -17,7 +17,7 @@ import { getResolutionsForScales } from '../../../utils/MapUtils';
  * @name withScalesDenominators
  * @memberof components.map.enhancers
  * @param {Component} Component this component is used to render the map, in the application contents: Maps, Dashboard, Geostory
- * @returns the map component with the resolutions calculated by fixed scales
+ * @returns {*} the map component with the resolutions calculated by fixed scales
  * @example
  * withScalesDenominators(MapPlugin);
  */

web/client/components/misc/AdaptiveGrid.jsx

@@ -24,7 +24,6 @@ const Grid = forceScrollTop(DataGrid);
  * @class
  * @memberof components.misc
  * @param  {props} props The props to pass to the ResizableGrid
- * @return {[type]}       [description]
  */
 export default (props) => (<ContainerDimensions>
     { ({ width, height }) =>

web/client/components/misc/enhancers/localizeStringMap.js

@@ -28,7 +28,7 @@ const accumulate = (props, locale) => (acc = {}, propName) => ({
  * ```
  * @name localizeStringMap
  * @memberof components.misc.enhancers
- * @param  {string|[string]} propNames Name of the prop(s) to replace. can be an array or a single prop
+ * @param  {string|string[]} propNames Name of the prop(s) to replace. can be an array or a single prop
  * @return {HOC}         An HOC that replaces the prop string with localized string.
  * @example
  * const Input = localizeStringMap('title')(TitleBar);

web/client/components/misc/enhancers/popover.js

@@ -17,7 +17,7 @@ import OverlayTrigger from '../../misc/OverlayTrigger';
  * Enhancer to add a popover to a component that triggers on mouse hover.
  * The new Component will look at the `popover` property (an object).
  * If present, as an object, can contain the properties to pass to th PopOver component (react-bootstrap),and the following props:
- * @prop {array[string]} popover.trigger trigger events array (see OverlayTrigger)
+ * @prop {string[]} popover.trigger trigger events array (see OverlayTrigger)
  * @prop {element} popover.text content of the popover
  * @type {function}
  * @name popover

web/client/epics/timeline.js

@@ -119,7 +119,7 @@ const RATIO = 5; // ratio of the size of the offset to set relative to the curre
  * @param {string} id layer id
  * @param {object} timeData the object that represent the domain source. Contains the URL to the service
  * @param {function} getState return the state of the application
- * @returns a stream of data with histogram and/or domain values
+ * @returns {*} a stream of data with histogram and/or domain values
  */
 const loadRangeData = (id, timeData, getState) => {
     let initialRange = rangeSelector(getState());

web/client/plugins/ContentTabs.jsx

@@ -29,6 +29,7 @@ const DefaultTitle = ({ item = {}, index }) => <span>{ item.title || `Tab ${inde
 
 /**
  * @deprecated
+ * @ignore
  * @name ContentTabs
  * @memberof plugins
  * @class

web/client/plugins/Contexts.jsx

@@ -187,6 +187,7 @@ const ContextsPlugin = compose(
  * Plugin for context resources browsing.
  * Can be rendered inside {@link #plugins.ContentTabs|ContentTabs} plugin
  * @deprecated
+ * @ignore
  * @name Contexts
  * @memberof plugins
  * @class

web/client/plugins/DashboardSave.jsx

@@ -46,6 +46,7 @@ const SaveBaseDialog = compose(
 /**
  * Implements "save" button for dashboards, to render in the {@link #plugins.BurgerMenu|BurgerMenu}}
  * @deprecated
+ * @ignore
  * @class
  * @name DashboardSave
  * @memberof plugins
@@ -102,6 +103,8 @@ export const DashboardSave = createPlugin('DashboardSave', {
 /**
  * Implements "save as" button for dashboards, to render in the {@link #plugins.BurgerMenu|BurgerMenu}}
  * @class
+ * @ignore
+ * @deprecated
  * @name DashboardSaveAs
  * @memberof plugins
  */

web/client/plugins/Dashboards.jsx

@@ -36,6 +36,7 @@ const dashboardsCountSelector = createSelector(
  * Can be rendered inside {@link #plugins.ContentTabs|ContentTabs} plugin
  * and adds an entry to the {@link #plugins.NavMenu|NavMenu}
  * @deprecated
+ * @ignore
  * @name Dashboards
  * @memberof plugins
  * @class

web/client/plugins/DeleteDashboard.jsx

@@ -21,7 +21,7 @@ import { isLoggedIn } from '../selectors/security';
 import Message from '../components/I18N/Message';
 /**
  * @deprecated
- *
+ * @ignore
  */
 class DeleteConfirmDialog extends React.Component {
 

web/client/plugins/DeleteGeoStory.jsx

@@ -21,7 +21,7 @@ import { isLoggedIn } from '../selectors/security';
 import Message from '../components/I18N/Message';
 /**
  * @deprecated
- *
+ * @ignore
  */
 class DeleteConfirmDialog extends React.Component {
 

web/client/plugins/DeleteMap.jsx

@@ -21,7 +21,7 @@ import { showConfirmDeleteMapModalSelector } from '../selectors/controls';
 import Message from '../components/I18N/Message';
 /**
  * @deprecated
- *
+ * @ignore
  */
 class DeleteConfirmDialog extends React.Component {
 

web/client/plugins/FeaturedMaps.jsx

@@ -185,6 +185,7 @@ const updateFeaturedMapsStream = mapPropsStream(props$ =>
  * FeaturedMaps plugin. Shows featured resources in a grid.
  * Typically used in the {@link #pages.Maps|home page}.
  * @deprecated
+ * @ignore
  * @name FeaturedMaps
  * @prop {string} cfg.pageSize change the page size (only desktop)
  * @prop {object} cfg.shareOptions configuration applied to share panel grouped by category name

web/client/plugins/GeoStories.jsx

@@ -35,6 +35,7 @@ const geostoriesCountSelector = createSelector(
  * Plugin for browsing GeoStory resources. Can render in {@link #plugins.ContentTabs|ContentTabs}
  * and adds an entry to the {@link #plugins.NavMenu|NavMenu}
  * @deprecated
+ * @ignore
  * @name Geostories
  * @class
  * @memberof plugins

web/client/plugins/GeoStorySave.jsx

@@ -66,6 +66,7 @@ const SaveBaseDialog = compose(
 /**
  * Implements "save" button for geostories, to render in the {@link #plugins.BurgerMenu|BurgerMenu}}
  * @deprecated
+ * @ignore
  * @class
  * @name GeoStorySave
  * @memberof plugins
@@ -104,6 +105,8 @@ export const GeoStorySave = createPlugin('GeoStorySave', {
 /**
  * Implements "save as" button for geostories, to render in the {@link #plugins.BurgerMenu|BurgerMenu}}
  * @class
+ * @deprecated
+ * @ignore
  * @name GeoStorySave
  * @memberof plugins
  */

web/client/plugins/Maps.jsx

@@ -163,6 +163,7 @@ const MapsPlugin = compose(
  * Can be rendered inside {@link #plugins.ContentTabs|ContentTabs} plugin
  * and adds an entry to the {@link #plugins.NavMenu|NavMenu}
  * @deprecated
+ * @ignore
  * @name Maps
  * @memberof plugins
  * @class

web/client/plugins/Permalink.jsx

@@ -17,7 +17,7 @@ import permalinkEpics from '../epics/permalink';
 import { permalinkLoadingSelector, permalinkSettingsSelector } from "../selectors/permalink";
 import Message from '../components/I18N/Message';
 
-/**
+/*
  * Permalink Component
  */
 const PermalinkComponent = connect(