Merge pull request #1212 from ORNL/1211-fix-jsdoc-errors

1211 fix jsdoc errors

core/database/foxx/api/data_router.js

@@ -1464,8 +1464,26 @@ router
     .summary("Toggle data record lock")
     .description("Toggle data record lock");
 
-/** @brief Get raw data path for local direct access, if possible from specified domain
+/**
+ * @function
+ * @description Gets the raw data path for local direct access from the specified domain,
+ * if available, for a given data ID and client.
  *
+ * The method checks the client's permissions for the data ID and returns the path to the data
+ * if the client has the required permissions and the data exists in the specified domain.
+ *
+ * @param {object} req - The request object, containing the query parameters.
+ * @param {object} req.queryParams - The query parameters provided in the request.
+ * @param {string} req.queryParams.client - The client ID for the request.
+ * @param {string} req.queryParams.id - The data ID (not alias) associated with the data.
+ * @param {string} req.queryParams.domain - The domain from which the data is being requested.
+ * @param {object} res - The response object, used to send the raw data path or error.
+ *
+ * @throws {Error} g_lib.ERR_PERM_DENIED - If the client does not have permission to read the data.
+ * @throws {Error} g_lib.ERR_NO_RAW_DATA - If the raw data is not found.
+ * @throws {Error} g_lib.ERR_INVALID_PARAM - If the data belongs to a different domain than specified.
+ *
+ * @returns {void} - Returns the raw data path in the response if the request is successful.
  */
 router
     .get("/path", function (req, res) {

core/database/foxx/api/process.js

@@ -6,14 +6,46 @@ const g_lib = require("./support");
 module.exports = (function () {
     var obj = {};
 
-    /** @brief Pre-process data/collection IDs for permissions and required data
+    /**
+     * @function
+     * Pre-processes data and collection IDs for permissions and required data.
+     *
+     * This function examines the specified data and collections for the appropriate permissions
+     * based on the given mode and recursively processes items (data/collections) in included collections.
+     * It does not resolve IDs. On success, it returns lists of data records for Globus and external data,
+     * as well as records without data. Additionally, it returns a flat list of all collections.
+     *
+     * In delete mode, only data that is not linked elsewhere will be returned for data records within collections.
+     *
+     * @param {object} a_client - The client object containing the client ID and admin status.
+     * @param {string} a_client._id - The unique identifier of the client.
+     * @param {boolean} a_client.is_admin - A flag indicating if the client is an administrator.
+     * @param {string} a_new_owner_id - The ID of the new owner to assign.
+     * @param {Array} a_ids - An array of data and collection IDs to process.
+     * @param {string} a_mode - The mode in which the operation is being performed. It can be one of the following:
+     * - `g_lib.TT_DATA_GET`: Read data permissions.
+     * - `g_lib.TT_DATA_PUT`: Write data permissions.
+     * - `g_lib.TT_REC_ALLOC_CHG`: Allocate/change record permissions.
+     * - `g_lib.TT_REC_OWNER_CHG`: Change record owner permissions.
+     * - `g_lib.TT_REC_DEL`: Delete record permissions.
+     * - `g_lib.TT_DATA_EXPORT`: Export data permissions.
      *
-     * Examine data and collections for proper permissions for the given mode and
-     * recursively process items (data/collections) in included collections. Does
-     * not resolve IDs. On success, returns lists of data records for globus and
-     * external data, as well as records without data. Also returns a flat list of
-     * all collections. In delete mode, for data records in collections, only data
-     * that isn't linked elsewhere are returned.
+     * @returns {object} ctxt - An object containing the following properties:
+     * - `client`: The client information.
+     * - `new_owner`: The ID of the new owner.
+     * - `mode`: The mode for the operation.
+     * - `coll_perm`: The collection permission level.
+     * - `data_perm`: The data permission level.
+     * - `coll`: A list of collections.
+     * - `glob_data`: A list of Globus data records.
+     * - `ext_data`: A list of external data records.
+     * - `visited`: A record of visited items during recursion.
+     *
+     * @throws {Error} g_lib.ERR_INVALID_MODE - If an invalid mode is passed.
+     *
+     * @example
+     * const result = obj.preprocessItems(client, newOwnerId, dataIds, g_lib.TT_DATA_GET);
+     * console.log(result.glob_data);
      */
     obj.preprocessItems = function (a_client, a_new_owner_id, a_ids, a_mode) {
         //console.log( "preprocessItems start" );
@@ -112,17 +144,20 @@ module.exports = (function () {
     };
 
     /**
-     * @brief Recursive preprocessing of data/collections for data operations
-     * @param a_ctxt - Recursion context object
-     * @param a_ids - Current list of data/collection IDs to process
-     * @param a_perm - Inherited permission (undefined initially)
+     * Recursively preprocesses data and collections for data operations.
+     *
+     * This function performs a depth-first analysis of collections, verifying permissions.
+     * It ensures that if the required permission is satisfied via inherited ACLs, no further
+     * permission checks are needed below that point. The function segregates collections and
+     * data into two categories: those with Globus data (regardless of data size) and those
+     * with external data. The final result is a flat list of collections and data.
+     *
+     * @param {object} a_ctxt - The recursion context object, containing relevant state such as permissions and mode.
+     * @param {Array} a_ids - The current list of data/collection IDs to process.
+     * @param {number} [a_data_perm] - The inherited data permission (undefined initially).
+     * @param {number} [a_coll_perm] - The inherited collection permission (undefined initially).
      *
-     * This function pre-processes with optimized permission verification by
-     * using a depth-first analysis of collections. If the required permission
-     * is satisfied via inherited ACLs, then no further permission checks are
-     * required below that point. The end result is a flat list of collections
-     * and data segregated into those with Globus data (regardless of data
-     * size) and those with external data.
+     * @throws {Array} Throws error with permission or parameter issues.
      */
     obj._preprocessItemsRecursive = function (a_ctxt, a_ids, a_data_perm, a_coll_perm) {
         var i, id, ids, is_coll, doc, perm, ok, data_perm, coll_perm;

core/database/foxx/api/repo_router.js

@@ -362,11 +362,19 @@ router
     .summary("Delete repo server record")
     .description("Delete repo server record");
 
-/** @brief Calculate the total, per-repo size of selected items
+/**
+ * @function
+ * @description Calculates the total, per-repo size of selected items.
+ * Recursively analyzes collections but only counts each data record once regardless of how many places it is linked.
+ * This function is used for pre-processing data move operations (e.g., changing allocation or owner).
  *
- * Recursively analyzes collections but only counts each data record once
- * regardless of how many places it is linked. Used for pre-processing
- * data move operations (change alloc or owner).
+ * @param {object} req - The request object, containing the query parameters.
+ * @param {object} res - The response object used to send the results.
+ * @returns {void} Sends an array of repository size statistics to the response.
+ *
+ * @example
+ * // Sample usage:
+ * router.get("/calc_size", function(req, res) { ... });
  */
 router
     .get("/calc_size", function (req, res) {

core/database/foxx/api/task_router.js

@@ -207,10 +207,21 @@ router
         "Run an initialized task. Step param confirms last command. Error message indicates external permanent failure.",
     );
 
-/** @brief Clean-up a task and remove it from task dependency graph
+/**
+ * @function
+ * @description Cleans up a task by removing it from the task dependency graph.
+ * It removes dependency locks and patches the task dependency graph both upstream and downstream.
+ * It returns a list of new runnable tasks if available.
  *
- * Removes dependency locks and patches task dependency graph (up and down
- * stream). Returns list of new runnable tasks if available.
+ * @param {object} req - The request object containing the task ID in the query parameters and other relevant data in the body.
+ * @param {object} res - The response object used to send the result or an error message.
+ * @returns {void} Sends a list of new runnable tasks to the response.
+ *
+ * @throws {Error} Throws an error if the task does not exist or if there's an issue processing the transaction.
+ *
+ * @example
+ * // Sample usage:
+ * router.post("/abort", function(req, res) { ... });
  */
 router
     .post("/abort", function (req, res) {

core/database/foxx/api/tasks.js

@@ -1498,14 +1498,21 @@ var tasks_func = (function () {
 
     // ----------------------- External Support Functions ---------------------
 
-    /** @brief Delete projects and associated data
+    /**
+     * Deletes one or more projects and associated data. If a project has no allocations, it can
+     * be deleted immediately. If a project has allocations and raw data, a task must be initialized
+     * to delete the allocations. Deletion is exclusive—if any other tasks are using the project or
+     * associated data, the operation will be denied.
      *
-     * Delete one or more projects. If a project has no allocations,
-     * it can be deleted immediately. If a project has allocations and
-     * raw data, the project can be deleted, but a task must be initialized
-     * to delete the allocations. Deletion is an exclusive operation - if
-     * any other tasks are using the project or associated data, the delete
-     * operation will be denied.
+     * @param {object} a_client - The client object that contains user details and permissions.
+     * @param {Array<string>} a_proj_ids - An array of project IDs to be deleted.
+     * @returns {object} An object containing the task to delete the projects and allocations.
+     * @throws {Array} Throws an error array containing a code and message if the project does
+     * not exist or the client lacks permissions.
+     *
+     * @example
+     * const result = obj.taskInitProjDelete(client, ['proj_id_1', 'proj_id_2']);
+     * console.log(result);
      */
     obj.taskInitProjDelete = function (a_client, a_proj_ids) {
         var i, proj_id;
@@ -2178,11 +2185,16 @@ var tasks_func = (function () {
         return doc;
     };
 
-    /** @brief Deletes a collection record
+    /**
+     * Deletes a collection record. This function should not be called directly and is used
+     * only by task or process code. The function does not recursively delete contained items.
      *
-     * NOTE: DO NOT CALL THIS DIRECTLY - USED ONLY BY TASK/PROCESS CODE
+     * @param {string} a_id - The ID of the collection to delete.
+     * @throws {Error} Throws an error if the collection or associated graph objects cannot be deleted.
      *
-     * Does not recursively delete contained items.
+     * This function will delete aliases, notes, topics, and tags associated with the collection,
+     * but it will not recursively delete contained items.
+     * Use this function only within tasks or process code.
      */
     obj._deleteCollection = function (a_id) {
         // Delete alias
@@ -2215,10 +2227,15 @@ var tasks_func = (function () {
         g_graph.c.remove(a_id);
     };
 
-    /** @brief Deletes data records
+    /**
+     * Deletes a data record and its associated graph objects. This function does not delete raw
+     * data but adjusts the allocation accordingly.
+     *
+     * @param {string} a_id - The ID of the data record to delete.
+     * @throws {Error} Throws an error if the data record or associated graph objects cannot be deleted.
      *
-     * Deletes record and associated graph objects. Does not delete raw data
-     * but does adjust allocation.
+     * This function will delete aliases, notes, tags, and update schema counts and allocations.
+     * It will not delete raw data, but it will adjust the allocation associated with the data record.
      */
     obj._deleteDataRecord = function (a_id) {
         //console.log( "delete rec", a_id );
@@ -2365,11 +2382,19 @@ var tasks_func = (function () {
         //console.log( "deleting records finished", Date.now() );
     };
 
-    /** @brief Deletes project immediately
+    /**
+     * Deletes a project and all associated graph objects immediately.
+     *
+     * This function deletes allocations, owned records (e.g., data, collections, groups),
+     * and the project itself. It performs a direct deletion of the project and its related
+     * items, and should **NOT** be used on projects containing raw data.
      *
-     * Deletes projects and associated graph objects.
+     * @param {string} a_proj_id - The ID of the project to delete.
+     * @throws {Error} Throws an error if the project or associated items cannot be deleted.
      *
-     * DO NOT USE ON PROJECTS WITH RAW DATA!!!!
+     * Use this function with caution, as it will permanently delete allocations, data,
+     * collections, groups, and the project. It should not be used for projects that
+     * contain raw data.
      */
     obj._projectDelete = function (a_proj_id) {
         console.log("_projectDelete", a_proj_id);

eslint.config.js

@@ -3,31 +3,31 @@ const jsdocPlugin = require("eslint-plugin-jsdoc");
 
 module.exports = [
     {
+        ignores: ["docs/_static/**/*", "web/static/jquery/jquery.js"],
         languageOptions: {
             globals: {
                 ...globals.jquery,
                 ...globals.node,
             },
         },
-        files: ['**/*.js', '**/*.ts'], // Adjust file patterns as needed
+        files: ["web/**/*.js", "web/**/*.ts", "core/**/*.js"], // Adjust file patterns as needed
         plugins: {
             jsdoc: jsdocPlugin,
         },
         rules: {
             // Enforce proper alignment and formatting of JSDoc
-            'jsdoc/check-alignment': 'error',
-            'jsdoc/check-indentation': 'error',
-            'jsdoc/check-param-names': 'error',
-            'jsdoc/check-tag-names': 'error',
-            'jsdoc/check-types': 'error',
-            'jsdoc/require-description': 'error',
-            'jsdoc/require-param': 'error',
-            'jsdoc/require-param-name': 'error',
-            'jsdoc/require-param-type': 'error',
-            'jsdoc/require-param-description': 'error',
-            'jsdoc/require-returns': 'error',
-            'jsdoc/require-returns-description': 'error',
-            'jsdoc/require-returns-type': 'error',
+            "jsdoc/check-alignment": "error",
+            "jsdoc/check-indentation": "error",
+            "jsdoc/check-param-names": "error",
+            "jsdoc/check-tag-names": "error",
+            "jsdoc/check-types": "error",
+            "jsdoc/require-param": "error",
+            "jsdoc/require-param-name": "error",
+            "jsdoc/require-param-type": "error",
+            "jsdoc/require-param-description": "error",
+            "jsdoc/require-returns": "error",
+            "jsdoc/require-returns-description": "error",
+            "jsdoc/require-returns-type": "error",
         },
-    }
+    },
 ];