js doc composer for interop with visual paradigm

.docs/build-diagrams.bat

@@ -0,0 +1,7 @@
+call jsdoc ../backend/app/App.js -t "./diagram-template/" -d "./out/App.h"
+call jsdoc ../backend/app/Config.js -t "./diagram-template/" -d "./out/Config.h"
+call jsdoc ../backend/app/Db.js -t "./diagram-template/" -d "./out/Db.h"
+call jsdoc ../backend/app/bl/GamesManager.js -t "./diagram-template/" -d "./out/bl/GamesManager.h"
+call jsdoc ../backend/app/bl/RulesManager.js -t "./diagram-template/" -d "./out/bl/RulesManager.h"
+call jsdoc ../backend/app/bl/GameObjectsManager.js -t "./diagram-template/" -d "./out/bl/GameObjectsManager.h"
+call jsdoc ../backend/app/bl/ScenariosManager.js -t "./diagram-template/" -d "./out/bl/ScenariosManager.h"

.docs/diagram-template/package.json

@@ -0,0 +1,3 @@
+{
+    
+}

.docs/diagram-template/publish.js

@@ -1,7 +1,13 @@
 const fs = require('fs');
 
+const typeMap = {
+    string: 'std::string',
+    Number: 'int'
+}
+
 function getType(t){
-    return (t?.type.names[0] || '').replace(/^Array\.\<(.*)\>$/, '$1*')
+    let tp = (t?.type?.names[0] || '').replace(/^Array\.\<(.*)\>$/, '$1*')
+    return typeMap[tp] || tp;
 }
 
 function graft(childNodes, parentLongname) {
@@ -9,12 +15,12 @@ function graft(childNodes, parentLongname) {
     childNodes.filter(({memberof}) => memberof === parentLongname)
     .forEach(element => {
         if (element.kind === 'function') {
-            result += `${getType(element.returns?.[0]) || 'void'} ${element.name}(${ element.params?.map(p=>
+            result += `/* ${element.description} */ ${getType(element.returns?.[0]) || 'void'} ${element.name}(${ element.params?.map(p=>
                 `/* ${p.description || ''} */ ${getType(p)} ${p.name}`
             ).join(', ') || ''});\n`;
         }
         else if (element.kind === 'member') {
-            result += `/* ${element.description || ''} */ ${getType(element)} ${element.name};`
+            result += `  /* ${element.description || ''} */ ${getType(element)} ${element.name};\n`
         }
         
         else if (element.kind === 'class') {
@@ -36,20 +42,9 @@ exports.publish = (data, {destination, query}) => {
     data({undocumented: true}).remove();
     docs = data().get(); // <-- an array of Doclet objects
 
-    fs.promises.writeFile('./result.json', JSON.stringify(docs), {encoding:'utf-8'})
+    fs.promises.writeFile(destination+'.json', JSON.stringify(docs, null, 2), {encoding:'utf-8'})
     
-    let result = graft(docs);
+    let result = `#include <string>\n\n` + graft(docs);
-    console.log(result)
+    //console.log(result)
-
+    fs.promises.writeFile(destination, result, {encoding:'utf-8'});
-    if (destination === 'console') {
-        if (query && query.format === 'xml') {
-            //console.log( xml.parse('xs:schema', root) );
-        }
-        else {
-            //console.log( require('jsdoc/util/dumper').dump(root) );
-        }
-    }
-    else {
-        console.log('This template only supports output to the console. Use the option "-d console" when you run JSDoc.');
-    }
 };

.gitignore

@@ -2,6 +2,7 @@
 node_modules
 /dist
 /out
+.docs/out/
 /repo
 
 #temporary:

backend/app/App.js

@@ -1,19 +1,33 @@
 import path, { dirname } from 'path';
 import { fileURLToPath } from 'url';
 
+/**
+ * Main backend application
+ */
 class App{
     constructor(){
         this.root = path.resolve(dirname(fileURLToPath(import.meta.url)) + '/../../');
     }
 
+    /**
+     * The plugins used by the application
+     * @type {AppPlugin[]}
+     */
     plugins = [];
 
+    /**
+     * Declaration of plugin usage
+     * @param {AppPlugin} plugin The plugin to be used
+     */
     async use(plugin){
         this[plugin.name] = plugin;
         plugin.app = this;
         this.plugins.push(plugin);
     }
 
+    /**
+     * Initializes the application. All plugins are initialized at this stage
+     */
     async init(){
         for (let p of this.plugins){
             console.debug('Initializing', p.name)
@@ -21,6 +35,10 @@ class App{
         }
     }
 
+    /**
+     * Imports modules as plugins in the app by a given list
+     * @param {Array} modules Modules to be imported
+     */
     async importModules(modules){
         const mods = {};
         for (let m of modules){
@@ -32,6 +50,10 @@ class App{
         }
     }
 
+    /**
+     * Replaces a plugin
+     * @param {AppPlugin} p Plugin to be replaced
+     */
     async replace(p){
         let old = this[p.name];
         this.plugins[this.plugins.indexOf(old)] = p;
@@ -40,6 +62,9 @@ class App{
         if(p.init) await p.init(this);
     }
 
+    /**
+     * Starts the application. All Plugins are started at this point
+     */
     async start(){
         for (let p of this.plugins){
             console.debug('Starting', p.name)

backend/app/Config.js

@@ -1,4 +1,8 @@
 import path from 'path'
+
+/**
+ * Configuration class
+ */
 class Config{
     name = 'config';
 
@@ -9,15 +13,35 @@ class Config{
         name:'pronature',
         url: "mongodb://127.0.0.1:27017/pronature"
     }
+
+    /**
+     * @class web site options 
+     * @alias SiteOptions
+     * @memberof Config
+     */
     site = {
+        /** Host name 
+         * @type {string} 
+         * @memberof SiteOptions
+         */
         host:'https://localhost:5173',
         ssl: true,
         port: 3000,
+        /** 
+         * @class certificate data
+         * @alias CertificateOptions
+         * @memberof SiteOptions
+         */
         certificate: {
+            /** 
+             * Certificate key 
+             * @type {string}
+             * @memberof CertificateOptions
+             */
             key: './.cert/dev-key.pem',
             cert: './.cert/dev-cert.pem',
             passphrase: 'parola'
-        }
+        },
     }
     am = { 
         salt : 'P@ssSal7y!!',

backend/app/Db.js

@@ -30,7 +30,7 @@ class Db {
      * Inserts a record in a db collection
      * @param {string} collection The name of the collection
      * @param {Object} value The object to insert
-     * @returns Inserted Id
+     * @returns {ObjectId} Inserted Id
      */
     async create(collection, value){
         try {
@@ -45,7 +45,7 @@ class Db {
      * @param {string} collection The name of the collection
      * @param {Object} key Record identifier
      * @param {Object} projection What data to take from the object 
-     * @returns A record
+     * @returns {Object} A record
      */
     async get(collection, key, projection){
         try {
@@ -59,7 +59,7 @@ class Db {
      * Performs a database query
      * @param {string} collection Collection name
      * @param {Object} query A mongo db query
-     * @returns Array of records
+     * @returns {Object[]} Array of records
      */
     async list(collection, query){
         try {

backend/app/bl/GamesManager.js

@@ -24,7 +24,7 @@ class GamesManager{
         /**
          * Reads game definition by ID
          * @param {Number} id game ID
-         * @returns {Game}
+         * @returns {Game} the game
          */
         this.read = async function(id){
 
@@ -50,7 +50,7 @@ class GamesManager{
         /**
          * Returns a set of games by given criteria
          * @param {Query} query criteria
-         * @returns {Game[]}
+         * @returns {Game[]} Array of games
          */
         this.list = async function(query){
 
@@ -73,18 +73,15 @@ class GamesManager{
 class Game {
     /**
      * Game name
-     * @type string
+     * @type {string}
      */
     name = null;
 
     /**
      * Game formal description
-     * @type GameDefinition
+     * @type {GameDefinition}
      */
     definition = {
-        /**
-         * 
-         */
         levels:[
             {
                 name: 'Level 1',

backend/app/bl/ScenariosManager.js

@@ -73,10 +73,114 @@ class ScenariosManager{
 class Scenario {
     /**
      * Scenario name
-     * @type string
+     * @type {string}
      */
     name = null;
 
+    /**
+     * Scenario levels
+     * @type {Level[]}
+     */
+    levels = [];
+}
+
+/**
+ * Game scenario level
+ */
+class Level {
+    /**
+     * Scenario name
+     * @type {string}
+     */
+    name = null;
+
+    /**
+     * Active objects
+     * @type {LevelObject[]}
+     */
+    activeObjects = []
+}
+
+/**
+ * Game object associated to a level
+ */
+class LevelObject {
+    /**
+     * Associated game object
+     * @type {GameObject}
+     */
+    gameObject = null;
+
+    /**
+     * Available actions
+     * @type {GameAction}
+     */
+    actions = []
+}
+
+/**
+ * Action associated to game object
+ */
+class GameAction {
+    /**
+     * Scenario name
+     * @type {string}
+     */
+    name = null;
+
+    /**
+     * Scenario name
+     * @type {string}
+     */
+    description = null;
+
+    /**
+     * Associated inventory item
+     * @type {InventoryItem}
+     */
+    inventoryItem = null;
+
+    /**
+     * Available outcomes from the action
+     * @type {GameActionResult}
+     */
+    results = []
+}
+
+/**
+ * Result associated to game action
+ */
+class GameActionResult{
+    pointsRuleDefinition = null;
+
+    /**
+     * Scenario name
+     * @type {string}
+     */
+    name = null;
+
+    /**
+     * Scenario name
+     * @type {string}
+     */
+    description = null;
+}
+
+/**
+ * Inventory item required to perform specific action
+ */
+class InventoryItem {
+    /**
+     * Scenario name
+     * @type {string}
+     */
+    name = null;
+
+    /**
+     * Scenario name
+     * @type {string}
+     */
+    description = null;
 }
 
 export { ScenariosManager }