#5817 [SDK] Add @module and @overview JSDoc Tag for TypeDoc Documentation Generation - Part I

Author: ThuF

components/api/api-modules-javascript/src/main/resources/META-INF/dirigible/modules/src/bpm/deployer.ts

@@ -1,7 +1,36 @@
 /**
- * API Deployer
- * * Provides methods for managing the lifecycle of Business Process Model and Notation (BPMN) definitions,
- * including deployment, undeployment, and deletion.
+ * @module bpm/deployer
+ * @overview
+ * This module provides functionalities for managing Business Process Model and Notation (BPMN) definitions,
+ * including deployment, undeployment, and deletion of process definitions.
+ * 
+ * ### Key Features
+ * - Deploy BPMN process definitions from specified locations (e.g., file paths).
+ * - Undeploy previously deployed process definitions based on their deployment location.
+ * - Permanently delete process definitions by their ID, with a reason for deletion.
+ * 
+ * ### Use Cases
+ * - Managing the lifecycle of BPMN process definitions in a workflow engine.
+ * - Automating deployment and cleanup of process definitions in development and production environments.
+ * - Integrating BPMN management into larger application workflows or administrative tools.
+ * 
+ * ### Example Usage
+ * ```ts
+ * import { Deployer } from "@aerokit/sdk/bpm";
+ * 
+ * // Deploy a new process definition
+ * const deploymentId = Deployer.deployProcess("/path/to/process.bpmn");
+ * console.log(`Deployed process with ID: ${deploymentId}`);
+ * 
+ * // Undeploy the process definition
+ * Deployer.undeployProcess("/path/to/process.bpmn");
+ * console.log("Undeployed process from location: /path/to/process.bpmn");
+ * 
+ * // Delete a deployed process definition by ID
+ * Deployer.deleteProcess(deploymentId, "Obsolete");
+ * console.log(`Deleted process with ID: ${deploymentId} for reason: Obsolete`);
+ * ```
+ *
  */
 
 const BpmFacade = Java.type("org.eclipse.dirigible.components.api.bpm.BpmFacade");

components/api/api-modules-javascript/src/main/resources/META-INF/dirigible/modules/src/bpm/process.ts

@@ -1,7 +1,30 @@
 /**
- * API Process
- * * Provides methods for interacting with process instances,
- * including starting, updating metadata, and managing variables.
+ * @module bpm/process
+ * @overview
+ * 
+ * This module provides functionalities for managing and interacting with BPMN process instances, including starting processes, updating metadata, and handling process variables.
+ * 
+ * ### Key Features
+ * - Start new process instances with optional business keys and parameters
+ * - Update process instance metadata such as name, business key, and business status
+ * - Manage process variables with support for local and global scopes, as well as transient variables
+ * 
+ * ### Use Cases
+ * - Initiating new process instances from application code
+ * - Dynamically updating process instance information during execution
+ * - Managing process variables for data storage and retrieval within process executions
+ * 
+ * ### Example Usage
+ * ```ts
+ * import { Process } from "@aerokit/sdk/bpm";
+ * // Start a new process instance
+ * const processInstanceId = Process.start("myProcessDefinitionKey", "myBusinessKey", { myVariable: "value" });
+ * console.log(`Started process instance with ID: ${processInstanceId}`);
+ * // Update process instance name
+ * Process.setProcessInstanceName(processInstanceId, "My Process Instance");
+ * // Set a process variable
+ * Process.setVariable(processInstanceId, "myVariable", "newValue");
+ * ```
  */
 
 import { Values } from "@aerokit/sdk/bpm/values";

components/api/api-modules-javascript/src/main/resources/META-INF/dirigible/modules/src/bpm/tasks.ts

@@ -1,5 +1,34 @@
 /**
- * API Tasks
+ * @module bpm/tasks
+ * @overview
+ * 
+ * This module provides functionalities for managing User Tasks within a Business Process Model and Notation (BPMN) context. It allows users to list tasks, manage task variables, complete tasks, and access task-related services.
+ * 
+ * ### Key Features
+ * - List all user tasks in the system
+ * - Get and set task variables, both globally and locally to the task
+ * - Complete tasks with optional variables and user information
+ * - Access the Task Service for advanced task management operations
+ * 
+ * ### Use Cases
+ * - Managing user tasks in a workflow engine
+ * - Automating task completion and variable management in development and production environments
+ * - Integrating task management into larger application workflows or administrative tools
+ * 
+ * ### Example Usage
+ * ```ts
+ * import { Tasks } from "@aerokit/sdk/bpm";
+ * // List all tasks
+ * const tasks = Tasks.list();
+ * console.log(tasks);
+ * // Get a task variable
+ * const variableValue = Tasks.getVariable("taskId", "variableName");
+ * console.log(variableValue);
+ * // Set a task variable
+ * Tasks.setVariable("taskId", "variableName", "newValue");
+ * // Complete a task with variables
+ * Tasks.complete("taskId", { "result": "approved" });
+ * ```
  */
 
 import { Streams } from "@aerokit/sdk/io";

components/api/api-modules-javascript/src/main/resources/META-INF/dirigible/modules/src/bpm/tracer.ts

@@ -1,3 +1,37 @@
+/**
+ * @module bpm/tracer
+ * @overview
+ * 
+ * This module provides a `Tracer` class for logging and tracing the execution of BPMN processes within the Dirigible environment. The `Tracer` class allows developers to log informational messages, warnings, and errors, as well as to track the duration of process execution from start to completion or failure.
+ * 
+ * ### Key Features
+ * - Context-aware logging: Automatically includes process definition ID, instance ID, business key, and activity ID in log messages.
+ * - Execution timing: Tracks the duration of process execution and logs it upon completion or failure.
+ * - Flexible logging levels: Supports informational, warning, and error logging.
+ * 
+ * ### Use Cases
+ * - Debugging and monitoring BPMN process execution in development and production environments.
+ * - Providing insights into process performance and identifying bottlenecks or issues.
+ * - Enhancing observability of BPMN processes for better maintenance and support.
+ * 
+ * ### Example Usage
+ * ```ts
+ * import { Tracer } from "@aerokit/sdk/bpm";
+ * 
+ * const tracer = new Tracer();
+ * try {
+ *   // Perform some operations related to the BPMN process
+ *   tracer.log("Performing step 1");
+ *   // ...
+ *   tracer.log("Performing step 2");
+ *  // ...
+ *  tracer.complete("Process completed successfully");
+ * } catch (error) {
+ *  tracer.fail(`Process failed with error: ${error.message}`);
+ * }
+ * ```
+ */
+
 import { Process } from '@aerokit/sdk/bpm';
 import { Logging, Logger } from "@aerokit/sdk/log";
 

components/api/api-modules-javascript/src/main/resources/META-INF/dirigible/modules/src/bpm/values.ts

@@ -1,8 +1,21 @@
 /**
- * Values
- * * Utility class for serializing (stringify) and deserializing (parse) complex variable values (like objects and arrays)
- * to and from JSON strings for storage or transfer across the API boundary.
+ * @module bpm/values
+ * @overview
+ * 
+ * The `Values` class provides utility methods for serializing and deserializing complex variable values (such as objects and arrays) to and from JSON strings. This is particularly useful for handling process variables in BPMN processes, where variables may need to be stored or transferred across API boundaries in a consistent format.
+ * 
+ * ### Key Features
+ * - **parseValue**: Safely attempts to parse a string value as JSON, returning the original value if parsing fails.
+ * - **parseValuesMap**: Applies JSON parsing to all values in a Map, allowing for bulk deserialization of process variables.
+ * - **stringifyValue**: Converts objects and arrays into their JSON string representations, while leaving primitive types unchanged. Arrays are also converted into Java Lists for compatibility with Java APIs.
+ * - **stringifyValuesMap**: Applies JSON stringification to all values in a Map, enabling bulk serialization of process variables before API calls.
+ * 
+ * ### Use Cases
+ * - Managing complex process variables in BPMN processes, including objects and arrays.
+ * - Ensuring consistent serialization and deserialization of variables when interacting with APIs that expect string values.
+ * - Facilitating the transfer of structured data across API boundaries in a format that can be easily parsed and utilized.
  */
+
 export class Values {
 
 	/**

components/api/api-modules-javascript/src/main/resources/META-INF/dirigible/modules/src/cache/cache.ts

@@ -1,8 +1,40 @@
 /**
- * Cache
- * * Provides a static utility for interacting with a server-side cache facade, enabling
- * simple key-value storage, retrieval, and invalidation operations.
+ * @module cache/cache
+ * @overview
+ * 
+ * This module provides a `Cache` class that serves as a static utility for interacting with a server-side cache facade. The `Cache` class allows developers to perform simple key-value storage, retrieval, and invalidation operations on the cache, enabling efficient data management and performance optimization within the Dirigible environment.
+ * 
+ * ### Key Features
+ * - Simple key-value storage: Store any serializable data in the cache using a unique key.
+ * - Efficient retrieval: Quickly retrieve cached values using their associated keys.
+ * - Cache invalidation: Remove specific entries or clear the entire cache when needed.
+ * - Server-side management: The cache is managed on the server, allowing for centralized control over caching behavior and policies.
+ * 
+ * ### Use Cases
+ * - Caching frequently accessed data to improve performance and reduce latency.
+ * - Storing intermediate results of expensive computations or API calls for reuse.
+ * - Managing session data or user-specific information in a scalable manner.
+ * - Implementing application-level caching strategies to optimize resource usage and response times.
+ * 
+ * ### Example Usage
+ * ```ts
+ * import { Cache } from "@aerokit/sdk/cache";
+ * 
+ * // Store a value in the cache
+ * Cache.set("user_123", { name: "Alice", age: 30 });
+ * // Retrieve a value from the cache
+ * const userData = Cache.get("user_123");
+ * console.log(userData); // Output: { name: "Alice", age: 30 }
+ * // Check if a key exists in the cache
+ * const exists = Cache.contains("user_123");
+ * console.log(exists); // Output: true
+ * // Delete a specific key from the cache
+ * Cache.delete("user_123");
+ * // Clear the entire cache
+ * Cache.clear();
+ * ```
  */
+
 const CacheFacade = Java.type("org.eclipse.dirigible.components.api.cache.CacheFacade");
 
 export class Cache {

components/api/api-modules-javascript/src/main/resources/META-INF/dirigible/modules/src/cms/cmis.ts

@@ -1,7 +1,30 @@
 /**
- * API CMIS
- * * Note: This module is supported only with the Mozilla Rhino engine
- * * Provides static access to the CMIS (Content Management Interoperability Services) repository session and utility constants.
+ * @module cms/cmis
+ * @overview
+ * 
+ * This module provides a set of classes and constants for interacting with a CMIS (Content Management Interoperability Services) repository within the Dirigible environment. It allows developers to establish sessions with the repository, navigate and manipulate folders and documents, and manage content streams. The module also defines standard CMIS properties and versioning states for consistent interaction with CMIS-compliant repositories.
+ * 
+ * ### Key Features
+ * - Establishing sessions with CMIS repositories
+ * - Navigating folder structures and managing documents
+ * - Handling content streams for document creation and retrieval
+ * - Defining standard CMIS properties and versioning states for consistent API usage
+ * 
+ * ### Use Cases
+ * - Integrating with enterprise content management systems that support CMIS
+ * - Building applications that require document management capabilities, such as file storage, versioning, and metadata handling
+ * - Automating content management tasks within a CMIS repository, such as bulk uploads, organization, and cleanup
+ * 
+ * ### Example Usage
+ * ```ts
+ * import { Cmis } from "@aerokit/sdk/cms";
+ * const session = Cmis.getSession();
+ * const rootFolder = session.getRootFolder();
+ * const newFolder = rootFolder.createFolder({ "cmis:name": "New Folder" });
+ * const contentStream = session.getObjectFactory().createContentStream("example.txt", 11, "text/plain", new streams.ByteArrayInputStream("Hello World".getBytes()));
+ * const newDocument = newFolder.createDocument({ "cmis:name": "Example Document" }, contentStream, Cmis.VERSIONING_STATE_MAJOR);
+ * console.log(`Created document with ID: ${newDocument.getId()} and name: ${newDocument.getName()}`);
+ * ```
  */
 
 import * as streams from "@aerokit/sdk/io/streams";

components/api/api-modules-javascript/src/main/resources/META-INF/dirigible/modules/src/component/decorators.ts

@@ -1,9 +1,37 @@
 /**
- * API DI (Dependency Injection) Decorators
- * * Provides a hybrid implementation of decorators for Dependency Injection (DI)
- * that supports both legacy JavaScript environments (like Mozilla Rhino or older GraalJS)
- * using the `(target, propertyKey)` signature, and modern JavaScript environments
- * using the decorator metadata and `context.addInitializer`.
+ * @module component/decorators
+ * @overview
+ * 
+ * This module provides a set of decorators for defining and managing Dependency Injection (DI) components within the Dirigible environment. The decorators are designed to be compatible with both legacy JavaScript environments (like Mozilla Rhino or older GraalJS) and modern JavaScript environments that support the latest decorator specifications.
+ * 
+ * ### Key Features
+ * - **Component Decorator**: Marks a class as a DI component, allowing it to be registered and managed by the DI container.
+ * - **Injected Decorator**: An alias for the Component decorator, used for semantic clarity when a class is intended to be injected as a dependency rather than being a primary component.
+ * - **Inject Decorator**: Marks a class property as an injection point, specifying that a dependency should be injected at runtime based on the property name or an optional custom name.
+ * - **Hybrid Decorator Support**: The decorators are implemented to work seamlessly in both legacy and modern JavaScript environments, ensuring broad compatibility across different runtime contexts.
+ * 
+ * ### Use Cases
+ * - Defining services, repositories, controllers, or any other components that require dependency injection in a Dirigible application.
+ * - Managing dependencies and promoting loose coupling between components for better maintainability and testability.
+ * - Leveraging the DI container to automatically resolve and inject dependencies based on component registration and metadata.
+ * 
+ * ### Example Usage
+ * ```ts
+ * import { Component, Inject } from "@aerokit/sdk/component";
+ * 
+ * @Component('MyService')
+ * class MyService {
+ *   // Service implementation
+ * }
+ * 
+ * @Component
+ * class MyController {
+ *   @Inject('MyService')
+ *   private myService!: MyService;
+ * 
+ *   // Controller implementation that uses myService
+ * }
+ * ```
  */
 
 const ComponentMetadataRegistry = Java.type(

components/api/api-modules-javascript/src/main/resources/META-INF/dirigible/modules/src/core/context.ts

@@ -1,6 +1,37 @@
 /**
- * API Context
- * * Provides a static interface for accessing and manipulating key-value pairs in a global, application-wide context.
+ * @module core/context
+ * @overview
+ * 
+ * The Context API provides a simple, static interface for storing and retrieving key-value pairs in a global application context. It allows components and modules to share data across the entire application without needing to pass values through function parameters or component props. The Context API is designed to be lightweight and easy to use, making it ideal for managing global state, configuration settings, or any other data that needs to be accessible throughout the application.
+ * 
+ * ### Key Features
+ * - **Global Accessibility**: Values stored in the context can be accessed from anywhere in the application, facilitating data sharing across components and modules.
+ * - **Simple API**: The Context API provides straightforward `get` and `set` methods for managing context values, making it easy to use without complex setup.
+ * - **Dynamic Storage**: The context can store any type of value, including primitives, objects, arrays, and even functions, allowing for flexible data management.
+ * - **Overwriting Values**: Setting a value with an existing name will overwrite the previous value, enabling dynamic updates to the context as needed.
+ * 
+ * ### Use Cases
+ * - Managing global configuration settings that need to be accessed by multiple components or modules.
+ * - Sharing state or data across different parts of the application without prop drilling or complex state management solutions.
+ * - Storing references to services, utilities, or other shared resources that need to be accessible throughout the application.
+ * - Facilitating communication between components that do not have a direct parent-child relationship by using the context as a shared data store.
+ * 
+ * ### Example Usage
+ * ```ts
+ * import { Context } from "@aerokit/sdk/core";
+ * 
+ * // Set a value in the context
+ * Context.set("apiEndpoint", "https://api.example.com");
+ * 
+ * // Get a value from the context
+ * const apiEndpoint = Context.get("apiEndpoint");
+ * console.log(apiEndpoint); // Output: "https://api.example.com"
+ * 
+ * // Overwrite an existing value in the context
+ * Context.set("apiEndpoint", "https://api.newexample.com");
+ * const newApiEndpoint = Context.get("apiEndpoint");
+ * console.log(newApiEndpoint); // Output: "https://api.newexample.com"
+ * ```
  */
 
 const ContextFacade = Java.type("org.eclipse.dirigible.components.api.core.ContextFacade");

components/api/api-modules-javascript/src/main/resources/META-INF/dirigible/modules/src/core/env.ts

@@ -1,6 +1,31 @@
 /**
- * API Env
- * * Provides a static interface for accessing and listing environment variables exposed to the runtime.
+ * @module core/env
+ * @description
+ * 
+ * The `Env` module provides a static interface for accessing environment variables exposed to the runtime. It allows you to retrieve individual environment variable values by name, as well as list all available environment variables in a structured format.
+ * 
+ * ### Key Features
+ * - **Simple Access**: Retrieve environment variable values using a straightforward `get` method.
+ * - **Comprehensive Listing**: Obtain a complete map of all environment variables using the `list` method, which returns an object with key-value pairs.
+ * - **Type Safety**: The `get` method returns `undefined` if an environment variable is not set, allowing for safe handling of missing variables.
+ * 
+ * ### Use Cases
+ * - Accessing configuration settings that are provided through environment variables, such as API keys, database connection strings, or feature flags.
+ * - Listing all available environment variables for debugging purposes or to dynamically adjust application behavior based on the runtime environment.
+ * - Integrating with external services that require environment variable configuration, ensuring that sensitive information is not hardcoded in the application code.
+ * 
+ * ### Example Usage
+ * ```ts
+ * import { Env } from "@aerokit/sdk/core";
+ * 
+ * // Get a specific environment variable
+ * const apiKey = Env.get("API_KEY");
+ * console.log(apiKey); // Output: "your-api-key" or undefined if not set
+ * 
+ * // List all environment variables
+ * const envVars = Env.list();
+ * console.log(envVars); // Output: { API_KEY: "your-api-key", NODE_ENV: "production", ... }
+ * ```
  */
 
 const EnvFacade = Java.type("org.eclipse.dirigible.components.api.core.EnvFacade");