Documentation

bin/backEnd.js

@@ -1,4 +1,12 @@
-/** @file main examples backend */
+/**
+ * @file Sets up an Express backend server for examples, serving static files,
+ * replacing HTML strings, and enabling a game socket service.
+ * The behavior adapts based on the environment mode and uses package.json configuration.
+ * @requires {@link https://www.npmjs.com/package/@ud-viz/node|@ud-viz/node}
+ * @requires {@link https://www.npmjs.com/package/@ud-viz/shared|@ud-viz/shared}
+ * @requires {@link https://www.npmjs.com/package/reload|reload}
+ * @requires {@link https://www.npmjs.com/package/string-replace-middleware|string-replace-middleware}
+ */
 
 const udvizNode = require('@ud-viz/node');
 const udvizVersion = require('../package.json').version;
@@ -7,13 +15,30 @@ const Constant = require('./Constant');
 const reload = require('reload');
 const { stringReplace } = require('string-replace-middleware');
 
-// run an express app wrapper with a gamesocket service
+/**
+ * The environment mode.
+ *
+ * @type {string}
+ */
 const NODE_ENV = process.env.NODE_ENV || 'development';
+
+/**
+ * The runtime mode determined by the environment.
+ *
+ * @type {string}
+ */
 const runMode = NODE_ENV === 'production' ? 'release' : 'debug';
 
-console.log('Back-end start on mode', runMode);
+console.log('Back-end starting in', runMode, 'mode');
 
+/**
+ * Express application instance.
+ *
+ * @type {object}
+ */
 const app = new udvizNode.express();
+
+// Apply string replacements for different values in HTML responses
 app.use(
   stringReplace(
     {
@@ -48,21 +73,28 @@ app.use(
   )
 );
 
+// Serve static files
 app.use(udvizNode.express.static('./'));
 
+/**
+ * The HTTP server instance.
+ *
+ * @type {object}
+ */
 const httpServer = app.listen(Constant.DEFAULT_PORT, (err) => {
   if (err) {
-    console.error('Server does not start');
+    console.error('Server could not start');
     return;
   }
   console.log('Http server listening on port', Constant.DEFAULT_PORT);
 });
 
-// initialize examples game socket service
+// Initialize examples game socket service
 const gameSocketService = new udvizNode.Game.SocketService(httpServer);
 gameSocketService
   .loadGameThreads(
     [
+      // Define the game thread
       new Game.Object3D({
         name: 'Note Game',
         static: true,
@@ -86,7 +118,7 @@ gameSocketService
   )
   .then(() => {
     console.log('Game SocketService initialized');
-    // if can send message to parent notify it
+    // Notify parent process if possible
     if (process.send) {
       process.send(Constant.MESSAGE.READY);
     }

bin/debug.js

@@ -1,20 +1,42 @@
-/** @file Running the build-debug script in the browser package. */
+/**
+ * @file This script executes build and runs the backend script.
+ *
+ * {@link https://www.npmjs.com/package/child-process-promise}
+ * {@link https://nodejs.org/api/child_process.html}
+ */
+
 const exec = require('child-process-promise').exec;
 const spawn = require('child_process').spawn;
 
 /**
- * It prints the stdout and stderr of a result object
+ * Prints the stdout and stderr of a command execution result.
  *
- * @param {{stdout:string,stderr:string}} result - The result of the command execution.
+ * @param {{stdout: string, stderr: string}} result - The result of the command execution.
  */
-const printExec = function (result) {
+function printExec(result) {
+  /**
+   * Log the standard output and standard error of a command execution result.
+   *
+   * @function
+   * @param {{stdout: string, stderr: string}} result - The result of the command execution.
+   */
   console.log('stdout: \n', result.stdout);
   console.log('stderr: \n', result.stderr);
-};
+}
 
+/**
+ * Execute the 'npm run build-debug' command and run the backend script.
+ */
 exec('npm run build-debug --prefix ./packages/browser')
   .then(printExec)
   .then(() => {
+    /**
+     * Spawn a child process to run the 'backEnd.js' script with specific settings.
+     *
+     * @param {string} command - The command to execute.
+     * @param {string[]} args - The arguments for the command.
+     * @param {object} options - The options for spawning the child process.
+     */
     const child = spawn(
       'cross-env NODE_ENV=development node',
       ['./bin/backEnd.js'],
@@ -23,9 +45,16 @@ exec('npm run build-debug --prefix ./packages/browser')
       }
     );
 
+    /**
+     * Log data from the child process's standard output.
+     */
     child.stdout.on('data', (data) => {
       console.log(`${data}`);
     });
+
+    /**
+     * Log error data from the child process's standard error in red color.
+     */
     child.stderr.on('data', (data) => {
       console.error('\x1b[31m', ` ERROR :\n${data}`);
     });

bin/prePublish.js

@@ -1,10 +1,30 @@
+/**
+ * @file Performs version management tasks within a monorepo:
+ * - Updates package.json files and dependencies to the provided version
+ * - Formats code with prettier
+ * - Executes reset and generates changelog diffs
+ * @param {string} version - The version to update to.
+ */
+
 const fs = require('fs');
 const exec = require('child-process-promise').exec;
 
+/**
+ * The version argument provided from the command line.
+ *
+ * @type {string}
+ */
 const version = process.argv[2];
 if (!version) throw new Error('no version argument found');
 
+/**
+ * The version split into segments.
+ *
+ * @type {string[]}
+ */
 const subStringVersion = version.split('.');
+
+/** Check the provided version argument. */
 if (subStringVersion.length != 3)
   throw new Error('Version format length error');
 subStringVersion.forEach((digit) => {
@@ -16,22 +36,29 @@ subStringVersion.forEach((digit) => {
 console.log('Change ud-viz-monorepo version to ', version);
 
 /**
- * It prints the stdout and stderr of a result object
+ * Prints the stdout and stderr of a command execution result.
  *
- * @param {{stdout:string,stderr:string}} result - The result of the command execution.
+ * @param {{stdout: string, stderr: string}} result - The result of the command execution.
  */
 const printExec = function (result) {
-  console.log('stdout: \n', result.stdout);
-  console.log('stderr: \n', result.stderr);
+  console.log('stdout:\n', result.stdout);
+  console.log('stderr:\n', result.stderr);
 };
 
+/**
+ * Updates the version number in a package.json file and updates the dependencies
+ * that start with "@ud-viz/" to the same version number.
+ *
+ * @param {string} path - The file path to the `package.json` file to update.
+ * @returns {Promise<void>} A Promise that resolves when the update is complete.
+ */
 const changeVersionPackageJSON = function (path) {
   return new Promise((resolve) => {
     console.log(path, '[x]');
     const content = JSON.parse(fs.readFileSync(path));
     content.version = version;
 
-    // update dependencie
+    // Update dependencies
     for (const key in content.dependencies) {
       if (key.startsWith('@ud-viz/')) {
         content.dependencies[key] = version;
@@ -45,17 +72,23 @@ const changeVersionPackageJSON = function (path) {
   });
 };
 
+// Update version and dependencies for multiple package.json files
 changeVersionPackageJSON('./packages/shared/package.json').then(() => {
   changeVersionPackageJSON('./packages/browser/package.json').then(() => {
     changeVersionPackageJSON('./packages/node/package.json').then(() => {
       changeVersionPackageJSON('./package.json').then(() => {
-        console.log('Start reset');
-        exec('npm run reset')
+        const commandReset = `npm run reset`;
+        console.log('RUN', commandReset);
+
+        // Execute reset command
+        exec(commandReset)
           .then(printExec)
           .then(() => {
-            exec(
-              `git describe --tags --match v* --abbrev=0 | xargs -I tag sh -c 'git log tag..HEAD --pretty=format:%s > ./docs/static/ChangelogDiff.txt'`
-            ).then(() => {
+            const commandGenerateChangelog = `git describe --tags --match v* --abbrev=0 | xargs -I tag sh -c 'git log tag..HEAD --pretty=format:%s > ./docs/static/ChangelogDiff.txt'`;
+            console.log('RUN', commandGenerateChangelog);
+
+            // Generate changelog diffs
+            exec(commandGenerateChangelog).then(() => {
               console.log(
                 'PrePublish done, you have to update ./docs/static/Changelog.md with ./docs/static/ChangelogDiff.txt'
               );

docs/jsdocConfig/jsdoc.js

@@ -1,3 +1,10 @@
+/**
+ * Merges JSDoc configuration files based on the provided PACKAGE environment variable.
+ * Generates documentation configuration for different packages (browser, node, shared, home).
+ *
+ * @returns {object} Merged JSDoc configuration.
+ */
+
 const { merge } = require('webpack-merge');
 
 const jsdocJson = {