doc: miscellaneous comment fixes

src/backend/src/modules/apps/AppInformationService.js

@@ -522,16 +522,14 @@ class AppInformationService extends BaseService {
     }
 
     /**
-    * Retrieves various statistics for a given app.
+    * Refreshes the application cache by querying the database for all apps and updating the key-value store.
     * 
-    * This method fetches the open count, user count, and referral count for an app identified by its UID.
-    * It uses cached values where available to improve performance, but will query the database if necessary.
+    * @async
+    * @returns {Promise<void>} A promise that resolves when the cache refresh operation is complete.
     * 
-    * @param {string} app_uid - The unique identifier of the app for which to retrieve stats.
-    * @returns {Promise<Object>} An object containing:
-    *   - {number} open_count - Total number of times the app was opened.
-    *   - {number} user_count - Number of unique users who opened the app.
-    *   - {number|null} referral_count - Number of referrals attributed to the app. This value might not be reported if not cached.
+    * @notes
+    * - This method logs a tick event for performance monitoring.
+    * - It populates the cache with app data indexed by name, id, and uid.
     */
     async _refresh_app_cache () {
         this.log.tick('refresh app cache');
@@ -548,14 +546,13 @@ class AppInformationService extends BaseService {
 
 
     /**
-    * Refreshes the application cache by querying the database for all apps and updating the key-value store.
-    * 
-    * @async
-    * @returns {Promise<void>} A promise that resolves when the cache refresh operation is complete.
-    * 
+    * Refreshes the cache of app statistics including open and user counts.
+    *
     * @notes
     * - This method logs a tick event for performance monitoring.
-    * - It populates the cache with app data indexed by name, id, and uid.
+    *
+    * @async
+    * @returns {Promise<void>} A promise that resolves when the cache refresh operation is complete.
     */
     async _refresh_app_stats () {
         this.log.tick('refresh app stats');
@@ -589,11 +586,17 @@ class AppInformationService extends BaseService {
 
 
     /**
-    * Refreshes the cache of app statistics including open and user counts.
-    * This method updates the cache every 120 seconds to ensure data freshness.
-    *
-    * @async
-    */
+     * Refreshes the cache of app referral statistics.
+     * 
+     * This method queries the database for user counts referred by each app's origin URL
+     * and updates the cache with the referral counts for each app.
+     * 
+     * @notes
+     * - This method logs a tick event for performance monitoring.
+     * 
+     * @async
+     * @returns {Promise<void>} A promise that resolves when the cache refresh operation is complete.
+     */
     async _refresh_app_stat_referrals () {
         this.log.tick('refresh app stat referrals');
 
@@ -653,12 +656,15 @@ class AppInformationService extends BaseService {
 
 
     /**
-    * Refreshes the cache of recently added or updated apps.
+    * Refreshes the cache of tags associated with apps.
     * 
-    * This method retrieves all apps from the cache, filters for approved listings,
-    * sorts them by timestamp in descending order, and updates the `recent` collection
-    * with the UIDs of the most recent 50 apps.
-    *
+    * This method iterates through all approved apps, extracts their tags,
+    * and organizes them into a structured format for quick lookups.
+    * 
+    * This data is used by the `/query/app` router to facilitate tag-based
+    * app discovery and categorization.
+    * 
+    * @async
     * @returns {Promise<void>}
     */
     async _refresh_tags () {

src/backend/src/modules/web/WebServerService.js

@@ -617,12 +617,13 @@ class WebServerService extends BaseService {
     }
 
     /**
-    * Starts the web server and sets up the necessary middleware and routes.
-    * This method is responsible for initializing the Express app, handling authentication,
-    * setting up routes, and starting the HTTP server. It also sets up error handling and
-    * socket.io for real-time communication.
-    *
-    * @param {Object} services - The services object containing all necessary services.
+    * Prints the Puter logo seen in the console after the server is started.
+    * 
+    * Depending on the size of the terminal, a different version of the
+    * logo is displayed. The logo is displayed in blue text.
+    * 
+    * @returns {void}
+    * @private
     */
     // comment above line 497
     print_puter_logo_() {

src/backend/src/services/AnomalyService.js

@@ -42,6 +42,16 @@ class AnomalyService extends BaseService {
     _construct () {
         this.types = {};
     }
+    /**
+     * Registers a new type with the service, including its configuration and handler.
+     * 
+     * @param {string} type - The name of the type to register.
+     * @param {Object} config - The configuration object for the type.
+     * @param {Function} [config.handler] - An optional handler function for the type.
+     * @param {number} [config.high] - An optional threshold value; triggers the handler if exceeded.
+     * 
+     * @returns {void}
+     */
     register (type, config) {
         const type_instance = {
             config,
@@ -58,14 +68,12 @@ class AnomalyService extends BaseService {
         this.types[type] = type_instance;
     }
     /**
-     * Registers a new type with the service, including its configuration and handler.
-     * 
-     * @param {string} type - The name of the type to register.
-     * @param {Object} config - The configuration object for the type.
-     * @param {Function} [config.handler] - An optional handler function for the type.
-     * @param {number} [config.high] - An optional threshold value; triggers the handler if exceeded.
+     * Creates a note of the specified type with the provided data.
+     * See `groups_user_hour` in GroupService for an example.
      * 
-     * @returns {void}
+     * @param {*} id - The identifier of the type to create a note for.
+     * @param {*} data - The data to process with the type's handler.
+     * @returns 
      */
     async note (id, data) {
         const type = this.types[id];

src/backend/src/services/BaseService.js

@@ -57,11 +57,10 @@ class BaseService extends concepts.Service {
 
 
     /**
-    * Initializes the service with configuration and dependencies.
-    * This method sets up logging and error handling, and calls a custom `_init` method if defined.
+    * Creates the service's data structures and initial values.
+    * This method sets up logging and error handling, and calls a custom `_construct` method if defined.
     * 
-    * @param {Object} args - Arguments passed to the service for initialization.
-    * @returns {Promise<void>} A promise that resolves when initialization is complete.
+    * @returns {Promise<void>} A promise that resolves when construction is complete.
     */
     async construct () {
         console.log('CLASS', this.constructor.name);

src/backend/src/services/CleanEmailService.js

@@ -76,17 +76,17 @@ class CleanEmailService extends BaseService {
         this.domain_nondistinct = this.constructor.DOMAIN_NONDISTINCT;
     }
 
+    /**
+    * Cleans an email address by applying provider-specific rules and standardizations
+    * @param {string} email - The email address to clean
+    * @returns {string} The cleaned email address with applied rules and standardizations
+    * 
+    * Splits email into local and domain parts, applies provider-specific rules like:
+    * - Removing dots for certain providers (Gmail, iCloud)
+    * - Handling subaddressing (removing +suffix)
+    * - Normalizing domains (e.g. googlemail.com -> gmail.com)
+    */
     clean (email) {
-        /**
-        * Cleans an email address by applying provider-specific rules and standardizations
-        * @param {string} email - The email address to clean
-        * @returns {string} The cleaned email address with applied rules and standardizations
-        * 
-        * Splits email into local and domain parts, applies provider-specific rules like:
-        * - Removing dots for certain providers (Gmail, iCloud)
-        * - Handling subaddressing (removing +suffix)
-        * - Normalizing domains (e.g. googlemail.com -> gmail.com)
-        */
         const eml = (() => {
             const [local, domain] = email.split('@');
             return { local, domain };

src/backend/src/services/EntityStoreService.js

@@ -39,6 +39,10 @@ class EntityStoreService extends BaseService {
     * @param {Object} args.upstream - The upstream service to handle operations.
     * 
     * @throws {Error} If `args.entity` is not provided.
+    *
+    * @returns {Promise<void>} A promise that resolves when initialization is complete.
+    * 
+    * @note This method sets up the context for the entity operations and provides it to the upstream service.
     */
     async _init (args) {
         if ( ! args.entity ) {
@@ -48,20 +52,6 @@ class EntityStoreService extends BaseService {
         this.upstream = args.upstream;
 
 
-        /**
-        * Initializes the EntityStoreService with the provided arguments.
-        * 
-        * @param {Object} args - Initialization arguments.
-        * @param {string} args.entity - The name of the entity this service will manage. 
-        *                              If not provided, an error is thrown.
-        * @param {Object} args.upstream - The upstream service or data source.
-        * 
-        * @throws {Error} If the entity name is not provided in the arguments.
-        * 
-        * @returns {Promise<void>} A promise that resolves when initialization is complete.
-        * 
-        * @note This method sets up the context for the entity operations and provides it to the upstream service.
-        */
         const context = Context.get().sub({ services: this.services });
         const om = this.services.get('registry').get('om:mapping').get(args.entity);
         this.om = om;
@@ -181,18 +171,19 @@ class EntityStoreService extends BaseService {
         if ( ! predicate) predicate = new Null();
         return await this.upstream.select({ predicate, ...rest });
     }
-    /**
-    * Retrieves entities matching a given predicate.
+    /* Updates an existing entity in the store.
     * 
-    * This method performs a selection query on the upstream data source.
-    * If no predicate is provided, it defaults to selecting all entities.
+    * @param {Object} entity - The entity to update with new values.
+    * @param {string|number} id - The identifier of the entity to update. Can be a string or number.
+    * @param {Object} options - Additional options for the update operation.
+    * @returns {Promise<Object>} The updated entity after the operation.
+    * @throws {APIError} If the entity to be updated is not found.
     * 
-    * @param {Object} options - The selection options.
-    * @param {Array|Function} options.predicate - The predicate for filtering entities. 
-    *      If an array, it's expected to be in the format [operator, ...args].
-    *      If not provided, it defaults to a Null predicate, effectively selecting all entities.
-    * @param {Object} [options.rest] - Additional options for the selection query.
-    * @returns {Promise<Array>} A promise that resolves to an array of entities matching the predicate.
+    * @note This method first attempts to fetch the entity by its primary identifier. If not found, 
+    *       it uses `IdentifierUtil` to detect and fetch by other identifiers if provided. 
+    *       If the entity still isn't found, an error is thrown. The method ensures that the 
+    *       entity's primary identifier is updated to match the existing entity before performing 
+    *       the actual update through `this.upstream.update`.
     */
     async update (entity, id, options) {
         let old_entity = await this.read(
@@ -225,7 +216,7 @@ class EntityStoreService extends BaseService {
         return await this.upstream.upsert(entity, { old_entity, options });
     }
     /**
-    * Updates an existing entity in the store.
+    * Updates an existing entity in the store or creates a new one.
     * 
     * @param {Object} entity - The entity to update with new values.
     * @param {string|number} id - The identifier of the entity to update. Can be a string or number.

src/backend/src/services/PuterHomepageService.js

@@ -78,9 +78,7 @@ class PuterHomepageService extends BaseService {
 
 
     /**
-    * @description This method sets a GUI parameter. It allows you to assign a value to a key within the `gui_params` object.
-    * @param {string} key - The key for the parameter.
-    * @param {any} val - The value for the parameter.
+    * This method sends the initial HTML page that loads the Puter GUI and its assets.
     */
     async send ({ req, res }, meta, launch_options) {
         const config = this.global_config;

src/backend/src/services/SessionService.js

@@ -89,12 +89,11 @@ class SessionService extends BaseService {
 
 
     /**
-    * Initializes the session service by setting up the database connection and scheduling periodic session updates.
+    * Creates a new session for the specified user and records metadata about
+    * the requestor.
     * 
     * @async
-    * @private
-    * @returns {Promise<void>} A promise that resolves when initialization is complete.
-    * @note This method is called internally during the service setup. It does not need to be invoked manually.
+    * @returns {Promise<Session>} A new session object
     */
     async create_session (user, meta) {
         const unix_ts = Math.floor(Date.now() / 1000);

src/backend/src/services/TrackSpendingService.js

@@ -33,13 +33,6 @@ const BaseService = require("./BaseService");
 * pricing strategies for chat completions and image generation services.
 */
 class TrackSpendingService extends BaseService {
-    /**
-    * @class TrackSpendingService
-    * @extends BaseService
-    * @description Service for tracking and monitoring API spending across different vendors and strategies.
-    * Implements cost tracking for chat completions and image generations, with configurable spending alerts.
-    * Maintains time-windowed spending metrics and triggers alarms when spending thresholds are exceeded.
-    */
     static ChatCompletionStrategy = class ChatCompletionStrategy {
         static models = {
             'gpt-4-1106-preview': {
@@ -217,11 +210,12 @@ class TrackSpendingService extends BaseService {
 
 
         /**
-        * Records spending data for a vendor using a specified strategy
-        * @param {string} vendor - The vendor name/identifier
-        * @param {string} strategy_key - Key identifying the pricing strategy to use
-        * @param {Object} data - Data needed to calculate cost based on the strategy
-        * @throws {Error} If strategy_key is invalid/unknown
+        * Generates alarms when spending exceeds configured thresholds
+        * 
+        * Periodically checks the current spending levels across all spending windows
+        * and triggers alarms when spending exceeds configured thresholds. Alarms are
+        * triggered based on the total spending across all windows and the configured
+        * alarm thresholds.
         */
         setInterval(() => {
             const spending = this.get_window_spending_();
@@ -281,6 +275,14 @@ class TrackSpendingService extends BaseService {
         }, 0);
     }
 
+    /**
+     * Records spending for a given vendor using the specified strategy
+     * 
+     * @param {string} vendor - The vendor name/identifier
+     * @param {string} strategy_key - Key identifying the pricing strategy to use
+     * @param {Object} data - Data needed to calculate cost based on the strategy
+     * @throws {Error} If strategy_key is invalid/unknown
+     */
     record_spending (vendor, strategy_key, data) {
         const strategy = this.strategies[strategy_key];
         if ( ! strategy ) {

src/backend/src/services/abuse-prevention/IdentificationService.js

@@ -140,13 +140,6 @@ class RequesterIdentificationExpressMiddleware extends AdvancedBase {
     install (app) {
         app.use(this.run.bind(this));
     }
-    /**
-    * Installs the middleware into the Express application.
-    * This method binds the `run` method to the current instance
-    * and uses it as a middleware function in the Express app.
-    *
-    * @param {object} app - The Express application instance.
-    */
     async run (req, res, next) {
         const x = Context.get();
 

src/backend/src/services/auth/PermissionService.js

@@ -134,12 +134,6 @@ class PermissionExploder {
         return this.matcher(permission);
     }
 
-    /**
-     * Check if the permission is implied by this implicator
-     * @param  {Actor} actor
-     * @param  {string} permission
-     * @returns 
-     */
     /**
     * Explodes a permission into a set of implied permissions.
     * 
@@ -785,15 +779,10 @@ class PermissionService extends BaseService {
      * - This was written for use in ll_listusers to display
      *   home directories of users that shared files with the
      *   current user.
+     *
+     * @param {Object} user - The user whose permission issuers are to be listed.
+     * @returns {Promise<Array>} A promise that resolves to an array of user objects.
      */
-    /**
-    * Lists users who have granted any permissions to the specified user.
-    * 
-    * This method provides a flat, non-recursive view of permission issuers.
-    * 
-    * @param {Object} user - The user whose permission issuers are to be listed.
-    * @returns {Promise<Array>} A promise that resolves to an array of user objects.
-    */
     async list_user_permission_issuers (user) {
         const rows = await this.db.read(
             'SELECT DISTINCT issuer_user_id FROM `user_to_user_permissions` ' +
@@ -822,17 +811,14 @@ class PermissionService extends BaseService {
      * Use History:
      * - This was written for FSNodeContext.fetchShares to query
      *   all the "shares" associated with a file.
+     * 
+     * This method retrieves permissions from the database where the permission key starts with a specified prefix.
+     * It is designed for "flat" (non-cascading) queries.
+     * 
+     * @param {Object} issuer - The actor granting the permissions.
+     * @param {string} prefix - The prefix to match in the permission key.
+     * @returns {Object} An object containing arrays of user and app permissions matching the prefix.
      */
-    /**
-    * Queries permissions granted by an issuer to various users and apps based on a permission prefix.
-    * 
-    * This method retrieves permissions from the database where the permission key starts with a specified prefix.
-    * It is designed for "flat" (non-cascading) queries.
-    * 
-    * @param {Object} issuer - The actor granting the permissions.
-    * @param {string} prefix - The prefix to match in the permission key.
-    * @returns {Object} An object containing arrays of user and app permissions matching the prefix.
-    */
     async query_issuer_permissions_by_prefix (issuer, prefix) {
         const user_perms = await this.db.read(
             'SELECT DISTINCT holder_user_id, permission ' +
@@ -881,22 +867,11 @@ class PermissionService extends BaseService {
      * 
      * This is a "flat" (non-cascading) view.
      *
-     * @param {*} issuer 
-     * @param {*} holder 
-     * @param {*} prefix 
-     * @returns 
+     * @param {Object} issuer - The actor granting the permissions.
+     * @param {Object} holder - The actor receiving the permissions.
+     * @param {string} prefix - The prefix of the permission keys to match.
+     * @returns {Promise<Array<string>>} An array of permission strings matching the prefix.
      */
-    /**
-    * Queries the permissions granted by an issuer to a holder with a specific prefix.
-    * 
-    * This method retrieves permissions that match a given prefix from the database.
-    * It's a flat view, meaning it does not include cascading permissions.
-    * 
-    * @param {Object} issuer - The actor granting the permissions.
-    * @param {Object} holder - The actor receiving the permissions.
-    * @param {string} prefix - The prefix of the permission keys to match.
-    * @returns {Promise<Array<string>>} An array of permission strings matching the prefix.
-    */
     async query_issuer_holder_permissions_by_prefix (issuer, holder, prefix) {
         const user_perms = await this.db.read(
             'SELECT permission ' +

src/backend/src/services/database/SqliteDatabaseAccessService.js

@@ -282,12 +282,7 @@ class SqliteDatabaseAccessService extends BaseDatabaseAccessService {
 
 
     /**
-    * Method to perform database upgrade if necessary.
-    *
-    * This method checks if the current database version is outdated and applies any necessary migration scripts to bring it up to date.
-    *
-    * @param {none}
-    * @returns {void}
+    * Implementation for prepared statements for READ operations.
     */
     async _read (query, params = []) {
         query = this.sqlite_transform_query_(query);
@@ -297,10 +292,9 @@ class SqliteDatabaseAccessService extends BaseDatabaseAccessService {
 
 
     /**
-    * @description This method initializes the SQLite database connection and performs any necessary upgrades to the database schema.
-    * @notes This method is responsible for creating a new instance of the SQLite database connection, registering commands for the SQLite CLI, and upgrading the database schema if necessary.
-    * @param {none}
-    * @return {Promise} A promise that resolves when the database connection is initialized and any necessary upgrades are completed.
+    * Implementation for prepared statements for READ operations.
+    * This method may perform additional steps to obtain the data, which
+    * is not applicable to the SQLite implementation.
     */
     async _requireRead (query, params) {
         return this._read(query, params);
@@ -308,11 +302,8 @@ class SqliteDatabaseAccessService extends BaseDatabaseAccessService {
 
 
     /**
-    * This method is responsible for performing database upgrades. It checks the current version of the database, compares it to the desired version, and applies any necessary migration scripts.
-    *
-    * It accepts no parameters and returns nothing.
-    */
-    // line 261, method begins here.
+     * Implementation for prepared statements for WRITE operations.
+     */
     async _write (query, params) {
         query = this.sqlite_transform_query_(query);
         params = this.sqlite_transform_params_(params);

src/backend/src/services/periodic/FSEntryMigrateService.js

@@ -55,9 +55,8 @@ class Job {
         return false;
     }
     /**
-    * Checks if the job should stop based on its current state
-    * @returns {boolean} True if the job should stop, false if it can continue
-    * @private
+    * Sets the job state to YELLOW, which means it will stop as soon as possible
+    * (generally after the current batch of work being processed)
     */
     stop () {
         this.state = this.constructor.STATE_YELLOW;