Integrate JSDoc (#26)

* Integrate JSDoc

* npm install

* Add core namespace + Stringifier class

.gitignore

@@ -1,3 +1,4 @@
 node_modules
 build
 types
+docs

jsdoc.json

@@ -0,0 +1,26 @@
+{
+  "plugins": [
+    "plugins/markdown",
+    "plugin-jsdoc-ts.cjs"
+  ],
+  "recurseDepth": 10,
+  "source": {
+    "include": ["src-transpiler"],
+    "includePattern": ".+\\.(js(doc|x)?|mjs)$"
+  },
+  "sourceType": "module",
+  "tags": {
+    "allowUnknownTags": true,
+    "dictionaries": ["jsdoc", "closure"]
+  },
+  "templates": {
+    "cleverLinks": false,
+    "monospaceLinks": false
+  },
+  "opts": {
+    "destination": "docs",
+    "encoding": "utf8",
+    "recurse": true,
+    "template": "./node_modules/@playcanvas/jsdoc-template"
+  }
+}

package.json

@@ -12,7 +12,7 @@
     "test": "npm run test:update && node test.mjs && node test_runtime.mjs",
     "test:update": "node gen_tests.mjs > test/typechecking.json",
     "lint": "eslint --ext .js,.mjs,.cjs src-transpiler src-runtime",
-    "docs": "echo todo docs using jsdoc"
+    "docs": "jsdoc -c jsdoc.json"
   },
   "repository": {
     "type": "git",
@@ -26,7 +26,11 @@
   "type": "module",
   "homepage": "https://github.com/kungfooman/RuntimeTypeInspector.js#readme",
   "devDependencies": {
+    "@babel/helper-plugin-utils": "^7.22.5",
+    "@babel/parser": "^7.23.0",
+    "@babel/plugin-syntax-typescript": "^7.22.5",
     "@babel/preset-env": "^7.22.20",
+    "@playcanvas/jsdoc-template": "^1.1.2",
     "@rollup/plugin-babel": "^6.0.3",
     "@rollup/plugin-commonjs": "^25.0.4",
     "@rollup/plugin-json": "^6.0.0",
@@ -35,17 +39,17 @@
     "@rollup/plugin-terser": "^0.4.3",
     "@rollup/pluginutils": "^5.0.4",
     "ace-builds": "^1.28.0",
+    "catharsis": "github:xenova/catharsis",
     "eslint": "^8.44.0",
     "eslint-plugin-import": "^2.28.1",
     "eslint-plugin-jsdoc": "^46.6.0",
+    "jsdoc": "^4.0.2",
+    "jsdoc-tsimport-plugin": "^1.0.5",
     "rollup": "^3.29.0",
     "rollup-plugin-dts": "^6.0.1",
     "rollup-plugin-jscc": "^2.0.0",
     "rollup-plugin-visualizer": "^5.9.2",
-    "to-fast-properties": "^4.0.0",
-    "@babel/helper-plugin-utils": "^7.22.5",
-    "@babel/parser": "^7.23.0",
-    "@babel/plugin-syntax-typescript": "^7.22.5"
+    "to-fast-properties": "^4.0.0"
   },
   "dependencies": {
     "@babel/core": "^7.2.0",

plugin-jsdoc-ts.cjs

@@ -0,0 +1,17 @@
+/*
+const catharsis = require("catharsis");
+const originalParse = catharsis.parse;
+catharsis.parse = function (str) {
+  // console.log("catharsis.parse-ts", str);
+  //if (str[0] == '[') {
+  //  return originalParse('Array<*>');
+  //}
+  try {
+    return originalParse(...arguments);
+  } catch (e) {
+    console.log("ERROR PARSING ", str);
+    return originalParse('any');
+    //return originalParse('any');
+  }
+};
+*/

src-transpiler/Stringifier.mjs

@@ -2,6 +2,9 @@ import {trimEndSpaces} from './trimEndSpaces.mjs';
 /**
  * @typedef {import("@babel/types").Node} Node
  */
+/**
+ * Class for converting AST into string.
+ */
 class Stringifier {
   forceCurly = false;
   /** @type {Node[]} */
@@ -247,7 +250,7 @@ class Stringifier {
   }
   numSpaces = 0;
   /**
-   * @returns {string} A string of two spaces per indentation.
+   * @type {string} A string of two spaces per indentation.
    */
   get spaces() {
     return '  '.repeat(this.numSpaces);

src-transpiler/index.mjs

@@ -1,3 +1,9 @@
+/**
+ * @name pc
+ * @todo rename, but needs more changes to template
+ * @namespace
+ * @description Root namespace for the RTI Transpiler.
+ */
 export * from './addTypeChecks.mjs';
 export * from './Asserter.mjs';
 export * from './ast2json.mjs';