doc: fix generated comment errors (batch 2)

src/backend/src/services/CommandService.js

@@ -78,20 +78,16 @@ class Command {
 */
 class CommandService extends BaseService {
     /**
-    * Service for managing and executing commands in the system.
-    * Extends BaseService to provide command registration, execution and lookup functionality.
-    * Commands are stored internally with unique IDs and can be executed with arguments.
-    * Built-in 'help' command is registered during initialization.
+    * Initializes the command service's internal state
+    * Called during service construction to set up the empty commands array
     */
     async _construct () {
         this.commands_ = [];
     }
+
     /**
-    * Initializes the command service's internal state
-    * Called during service construction to set up the empty commands array
-    * @private
-    * @returns {Promise<void>}
-    */
+     * Add the help command to the list of commands on init
+     */
     async _init () {
         this.commands_.push(new Command({
             id: 'help',

src/backend/src/services/CommentService.js

@@ -36,13 +36,13 @@ const { DB_WRITE } = require("./database/consts");
 * @extends BaseService
 */
 class CommentService extends BaseService {
-    static MODULES = {
-        uuidv4: require('uuid').v4,
-    }
     /**
     * Static module dependencies used by the CommentService class
     * @property {Function} uuidv4 - UUID v4 generator function from the uuid package
     */
+    static MODULES = {
+        uuidv4: require('uuid').v4,
+    }
     _init () {
         const svc_database = this.services.get('database');
         this.db = svc_database.get(DB_WRITE, 'notification');

src/backend/src/services/ConfigurableCountingService.js

@@ -33,8 +33,8 @@ const hash = v => {
 * @class ConfigurableCountingService
 * @extends BaseService
 * @description The ConfigurableCountingService class extends BaseService and is responsible for managing and incrementing
-*              configurable counting types for different services. It handles the initialization of the database connection,
-*              defines counting types and SQL columns, and provides a method to increment counts based on specific service
+*              configurable counting types for different services.
+*              It defines counting types and SQL columns, and provides a method to increment counts based on specific service
 *              types and values. This class is used to manage usage counts for various services, ensuring accurate tracking
 *              and updating of counts in the database.
 */
@@ -86,7 +86,7 @@ class ConfigurableCountingService extends BaseService {
 
 
     /**
-    * Initializes the database connection for the ConfigurableCountingService.
+    * Initializes the database accessor for the ConfigurableCountingService.
     * This method sets up the database service for writing counting data.
     *
     * @async

src/backend/src/services/Container.js

@@ -67,7 +67,7 @@ class Container {
     }
 
     /**
-     * registerService registers a service with the servuces container.
+     * registerService registers a service with the services container.
      * 
      * @param {String} name - the name of the service
      * @param {BaseService.constructor} cls - an implementation of BaseService
@@ -134,13 +134,13 @@ class Container {
             throw new Error(`missing service: ${name}`);
         }
     }
-    has (name) { return !! this.instances_[name]; }
     /**
     * Checks if a service is registered in the container.
     *
     * @param {String} name - The name of the service to check.
     * @returns {Boolean} - Returns true if the service is registered, false otherwise.
     */
+    has (name) { return !! this.instances_[name]; }
     get values () {
         const values = {};
         for ( const k in this.instances_ ) {
@@ -245,18 +245,18 @@ class ProxyContainer {
         }
         return this.delegate.get(name);
     }
-    has (name) {
-        if ( this.instances_.hasOwnProperty(name) ) {
-            return true;
-        }
-        return this.delegate.has(name);
-    }
     /**
     * Checks if the container has a service with the specified name.
     *
     * @param {string} name - The name of the service to check.
     * @returns {boolean} - Returns true if the service exists, false otherwise.
     */
+    has (name) {
+        if ( this.instances_.hasOwnProperty(name) ) {
+            return true;
+        }
+        return this.delegate.has(name);
+    }
     get values () {
         const values = {};
         Object.assign(values, this.delegate.values);

src/backend/src/services/ContextInitService.js

@@ -36,8 +36,6 @@ class ContextInitExpressMiddleware {
     * Manages a list of value initializers that populate the Context with
     * either static values or async-generated values when handling requests.
     * Part of DRY pattern with src/util/context.js.
-    * 
-    * @class
     */
     constructor () {
         this.value_initializers_ = [];
@@ -91,16 +89,16 @@ class ContextInitService extends BaseService {
             key, value,
         });
     }
-    register_async_factory (key, async_factory) {
-        this.mw.register_initializer({
-            key, async_factory,
-        });
-    }
     /**
     * Registers an asynchronous factory function to initialize a context value
     * @param {string} key - The key to store the value under in the context
     * @param {Function} async_factory - Async function that returns the value to store
     */
+    register_async_factory (key, async_factory) {
+        this.mw.register_initializer({
+            key, async_factory,
+        });
+    }
     async ['__on_install.middlewares.context-aware'] (_, { app }) {
         this.mw.install(app);
         await this.services.emit('install.context-initializers');

src/backend/src/services/DetailProviderService.js

@@ -24,23 +24,7 @@ const BaseService = require("./BaseService")
  * detail providers. A detail provider is a function that takes an
  * input object and uses its values to populate another object.
  */
-/**
-* @class DetailProviderService
-* @extends BaseService
-* @description This class manages a collection of detail providers, 
-* which are functions that accept an input object to populate another object 
-* with relevant details. It provides methods to register new providers and 
-* retrieve details using all registered providers in sequence.
-*/
 class DetailProviderService extends BaseService {
-    /**
-    * Retrieves detailed information by invoking all registered detail providers with the given context.
-    * Each provider is expected to modify the out object directly.
-    * 
-    * @param {Object} context - The input context for the providers.
-    * @param {Object} [out={}] - An object to store the combined results from each provider.
-    * @returns {Object} The combined results populated by the detail providers.
-    */
     _construct () {
         this.providers_ = [];
     }
@@ -52,7 +36,7 @@ class DetailProviderService extends BaseService {
 
     /**
     * Asynchronously retrieves details by invoking registered detail providers
-    * in sequence. Populates the provided output object with the results of 
+    * in list. Populates the provided output object with the results of 
     * each provider. If no output object is provided, a new one is created 
     * by default.
     *

src/backend/src/services/DevConsoleService.js

@@ -226,14 +226,9 @@ class DevConsoleService extends BaseService {
 
 
         /**
-        * Handles the initialization of the DevConsole service, setting up
-        * command line interface and managing input/output operations.
+        * _before_cmd - Handles operations needed before a command is executed.
         * 
-        * This method creates a readline interface for user input, processes
-        * commands, and manages the display of command output in the console.
-        * 
-        * @async
-        * @returns {Promise<void>} A promise that resolves when the initialization is complete.
+        * (resets cursor to correct position, if I recall correctly)
         */
         this._before_cmd = () => {
             rl.pause();
@@ -279,10 +274,8 @@ class DevConsoleService extends BaseService {
 
 
         /**
-        * Prepares the console for output by performing necessary actions 
-        * such as clearing previous lines and setting up the environment 
-        * for rendering new output. This method is called before new
-        * data is written to the console.
+        * Re-draws static lines and the input prompt (everything at the bottom of
+        * the dev console) when something is written.
         */
         this._post_write = () => {
             this.update_();
@@ -337,9 +330,6 @@ class DevConsoleService extends BaseService {
             }
         }, 2000);
 
-        consoleLogManager.decorate_all(({ replace }, ...args) => {
-            this._pre_write();
-        });
         /**
         * Decorates all console log messages with the specified pre-write actions.
         * 
@@ -349,6 +339,10 @@ class DevConsoleService extends BaseService {
         * 
         * It does not accept any parameters and does not return any value.
         */
+        consoleLogManager.decorate_all(({ replace }, ...args) => {
+            this._pre_write();
+        });
+
         consoleLogManager.post_all(() => {
             this._post_write();
         })

src/backend/src/services/DevTODService.js

@@ -69,19 +69,21 @@ const wordwrap = (text, width) => {
 */
 class DevTODService extends BaseService {
     /**
-    * DevTODService class - Manages "Tip of the Day" functionality for the developer console
-    * @extends BaseService
-    * @description Provides random development tips and console commands for managing tip display
-    * Integrates with the dev console to show helpful tips about source code and CLI usage
+    * Initializes the DevTODService by registering commands with the command service
+    * @private
+    * @async
+    * @returns {Promise<void>}
     */
     async _init () {
         const svc_commands = this.services.get('commands');
         this._register_commands(svc_commands);
     }
+
     /**
-    * Initializes the DevTODService by registering commands with the command service
-    * @private
-    * @async
+    * Handles the boot consolidation phase for the Tip of the Day service
+    * Selects a random tip, wraps it to fit the console width, and creates
+    * a widget function to display the formatted tip with optional header/footer
+    * 
     * @returns {Promise<void>}
     */
     async ['__on_boot.consolidation'] () {
@@ -91,13 +93,6 @@ class DevTODService extends BaseService {
             process.stdout.columns
                 ? process.stdout.columns - 6 : 50
         );
-        /**
-        * Handles the boot consolidation phase for the Tip of the Day service
-        * Selects a random tip, wraps it to fit the console width, and creates
-        * a widget function to display the formatted tip with optional header/footer
-        * 
-        * @returns {Promise<void>}
-        */
         this.tod_widget = () => {
             const lines = [
                 ...random_tip,

src/backend/src/services/EntityStoreService.js

@@ -136,11 +136,11 @@ class EntityStoreService extends BaseService {
 
     // TODO: can replace these with MethodProxyFeature
     /**
-    * Retrieves an entity by its unique identifier.
+    * Create a new entity in the store.
     * 
-    * @param {string} uid - The unique identifier of the entity to read.
-    * @returns {Promise<Object>} The entity object if found, otherwise null or throws an error.
-    * @throws {APIError} If the entity with the given uid does not exist.
+    * @param {Object} entity - The entity to add.
+    * @param {Object} options - Additional options for the update operation.
+    * @returns {Promise<Object>} The updated entity after the operation.
     */
     async create (entity, options) {
         return await this.upstream.upsert(entity, { old_entity: null, options });

src/backend/src/services/EventService.js

@@ -22,11 +22,10 @@ const BaseService = require("./BaseService");
 
 
 /**
-* EventService class extends BaseService to provide a mechanism for 
-* emitting and listening to events within the application. It manages
-* event listeners scoped to specific keys and allows global listeners
-* for broader event handling.
-*/
+ * A proxy to EventService or another scoped event bus, allowing for
+ * emitting or listening on a prefix (ex: `a.b.c`) without the user
+ * of the scoped bus needed to know what the prefix is.
+ */
 class ScopedEventBus {
     constructor (event_bus, scope) {
         this.event_bus = event_bus;
@@ -119,24 +118,24 @@ class EventService extends BaseService {
 
     }
 
+    /**
+    * Registers a callback function for the specified event selector.
+    * 
+    * This method will push the provided callback onto the list of listeners
+    * for the event specified by the selector. It returns an object containing
+    * a detach method, which can be used to remove the listener.
+    *
+    * @param {string} selector - The event selector to listen for.
+    * @param {Function} callback - The function to be invoked when the event is emitted.
+    * @returns {Object} An object with a detach method to unsubscribe the listener.
+    */
     on (selector, callback) {
         const listeners = this.listeners_[selector] ||
             (this.listeners_[selector] = []);
 
         listeners.push(callback);
 
         const det = {
-            /**
-            * Registers a callback function for the specified event selector.
-            * 
-            * This method will push the provided callback onto the list of listeners
-            * for the event specified by the selector. It returns an object containing
-            * a detach method, which can be used to remove the listener.
-            *
-            * @param {string} selector - The event selector to listen for.
-            * @param {Function} callback - The function to be invoked when the event is emitted.
-            * @returns {Object} An object with a detach method to unsubscribe the listener.
-            */
             detach: () => {
                 const idx = listeners.indexOf(callback);
                 if ( idx !== -1 ) {