Replace jsdoc with typedoc

Use TypeDoc instead of JSDoc because it has better support for
documenting TypeScript APIs.

docs/jsdoc.json

@@ -1,25 +0,0 @@
-{
-	"plugins": [
-		"plugins/markdown"
-	],
-	"tags": {
-		"allowUnknownTags": false
-	},
-	"opts": {
-		"destination": "docs/api",
-		"recurse": true
-	},
-	"source": {
-		"include": [
-			"packages/controller/src/",
-			"packages/controller/controller.js",
-			"packages/host/src/",
-			"packages/host/host.js",
-			"packages/ctl/src/",
-			"packages/ctl/ctl.js",
-			"packages/lib/",
-			"plugins/"
-		],
-		"excludePattern": "node_modules"
-	}
-}

package.json

@@ -9,7 +9,7 @@
     "ci-cover": "nyc --reporter=lcovonly pnpm run-script test",
     "lint": "eslint \"*.js\" packages plugins test",
     "lint-fix": "eslint --fix \"*.js\" packages plugins test",
-    "docs": "jsdoc --configure docs/jsdoc.json",
+    "docs": "typedoc",
     "bundle-dependencies": "bundle-dependencies"
   },
   "nyc": {
@@ -31,11 +31,11 @@
     "express": "^4.18.2",
     "form-data": "^4.0.0",
     "fs-extra": "^11.1.1",
-    "jsdoc": "^4.0.2",
     "jsonwebtoken": "^9.0.1",
     "jszip": "^3.10.0",
     "mocha": "^10.2.0",
     "nyc": "^15.1.0",
-    "phin": "^3.7.0"
+    "phin": "^3.7.0",
+    "typedoc": "^0.24.8"
   }
 }

packages/lib/src/factorio/exchange_string.js

@@ -324,7 +324,7 @@ function readMapSettings(state) {
 }
 
 /**
- * @typedef {object} module:lib.MapExchangeResult
+ * @typedef {object} MapExchangeResult
  * @property {array} version -
  *     Version of Factorio the string was created with.
  * @property {object} map_gen_settings -
@@ -344,7 +344,7 @@ function readMapSettings(state) {
  * save to set the map gen settings and the map settings for the save.
  *
  * @param {string} exchangeString - Max Exchange String to parse.
- * @returns {module:lib.MapExchangeResult} Parsed result.
+ * @returns {MapExchangeResult} Parsed result.
  * @memberof module:lib
  */
 function readMapExchangeString(exchangeString) {

packages/lib/src/helpers.js

@@ -210,18 +210,18 @@ function wordMatches(word, ...texts) {
 }
 
 /**
- * @typedef {object} module:lib~ParsedTerm
+ * @typedef {object} ParsedTerm
  * @property {string} type - Type of term, either attribute or word.
  * @property {string=} name - attribute only: Name of attribute.
  * @property {boolean=} exclude - word only: exclude results with this word.
- * @property {string | module:lib.ParsedTerm} value -
+ * @property {string | ParsedTerm} value -
  *     Parsed value of this term. Is a string if type is word, and a
  *     ParsedTerm if type is attribute.
  */
 
 /**
- * @typedef {object} module:lib~ParsedSearch
- * @property {Array<module:lib~ParsedTerm>} terms -
+ * @typedef {object} ParsedSearch
+ * @property {Array<ParsedTerm>} terms -
  *     Parsed result of search terms.
  * @property {Array<string>} issues -
  *     Issues detected while parsing the seach string.
@@ -248,7 +248,7 @@ function wordMatches(word, ...texts) {
  * @param {Object<string, string>} attributes -
  *     Recognized attributes and their format. Currently only word is
  *     supported.
- * @returns {module:lib~ParsedSearch} parsed terms of the search.
+ * @returns {ParsedSearch} parsed terms of the search.
  * @static
  */
 function parseSearchString(input, attributes = {}) {

packages/lib/src/logging.js

@@ -84,7 +84,7 @@ class WebConsoleFormat {
 
 /**
  * Filter object for logs
- * @typedef {Object} module:lib~LogFilter
+ * @typedef {Object} LogFilter
  * @property {string} [maxLevel] -
  *     Maximum log level to include. Higher levels are more verbose.
  * @property {boolean} [all] -
@@ -101,7 +101,7 @@ class WebConsoleFormat {
 /**
  * Create log filter by level and source.
  *
- * @param {module:lib~LogFilter} filter -
+ * @param {LogFilter} filter -
  *     Filter to filter log entries by.
  * @returns {function(object): boolean}
  *     filter returning true for log entries that match it.

packages/lib/src/logging_utils.js

@@ -275,7 +275,7 @@ class LogIndex {
 	 *
 	 * @param {string} file -
 	 *     Name of file in the log directory to check for.
-	 * @param {module:lib~LogFilter} filter -
+	 * @param {LogFilter} filter -
 	 *     Filter to check index if file contains entries for.
 	 * @returns {boolean}
 	 *     true if the file may contain entries included by the filter.
@@ -314,7 +314,7 @@ class LogIndex {
 
 /**
  * Filter object for querying logs
- * @typedef {Object} module:lib~QueryLogFilter
+ * @typedef {Object} QueryLogFilter
  * @property {number} [limit=100] - Maximum number of entries to return.
  * @property {string} [order="asc"] -
  *     Return entries in ascending ("asc") date order or desceding ("desc")
@@ -336,7 +336,7 @@ class LogIndex {
  * Query log directory
  *
  * @param {string} logDirectory - path to directory with logs.
- * @param {module:lib~QueryLogFilter} filter -
+ * @param {QueryLogFilter} filter -
  *     Filter to limit logs by.
  * @param {module:lib.LogIndex=} index -
  *     Index to speed up query with.

packages/lib/src/plugin.js

@@ -6,13 +6,13 @@
 
 const helpers = require("./helpers");
 
-/**
+/* TODO fix when converting to ts
  * Conceptual base for controller and instance plugins.
  * @typedef {
- *     module:lib.BaseControllerPlugin
- *     |module:lib.BaseInstancePlugin
- *     |module:lib.BaseControlPlugin
- * } module:lib.BasePlugin
+ *     BaseControllerPlugin
+ *     |BaseInstancePlugin
+ *     |BaseControlPlugin
+ * } BasePlugin
  */
 
 /**
@@ -612,7 +612,7 @@ class BaseControlPlugin {
 
 /**
  * Plugin supplied login form
- * @typedef {Object} module:lib~LoginForm
+ * @typedef {Object} LoginForm
  * @property {string} name -
  *     Internal name of the login form, this should start with the
  *     plugin name followed by a dot.
@@ -627,7 +627,7 @@ class BaseControlPlugin {
 
 /**
  * Plugin supplied pages
- * @typedef {Object} module:lib~Page
+ * @typedef {Object} Page
  * @property {string} path - URL path to this page.
  * @property {string=} sidebarPath -
  *     If present and this path matches one of the pages in the sidebar it

packages/lib/typedoc.json

@@ -0,0 +1,4 @@
+{
+  "entryPoints": ["index.ts"],
+  "includeVersion": true
+}

typedoc.json

@@ -0,0 +1,7 @@
+{
+    "$schema": "https://typedoc.org/schema.json",
+    "entryPoints": ["packages/lib/"],
+    "entryPointStrategy": "packages",
+    "cleanOutputDir": false,
+    "out": "docs/api"
+}