chore: typedoc markdown (#9146)

* chore: add typedoc-plugin-markdown at workplace root

* chore: add a typedoc-markdown script target to generate typedoc in md

* fix(docs): close the quote properly

* fix(docs): put raw <T> tag in quotes

* chore: add `--tsconfig tsconfig.build.json` to be inline with `yarn docs`

* ci: add a step to verify yarn typedoc-markdown is successful

* chore: change the yarn script target to be more explicit

.github/workflows/test-all-packages.yml

@@ -75,6 +75,9 @@ jobs:
       # build the API docs to verify it works
       - name: build API docs
         run: yarn docs
+      # build the API docs in markdown for agoric/documentation repo to verify it works
+      - name: build API docs in markdown
+        run: yarn docs:markdown-for-agoric-documentation-repo
 
   lint-rest:
     timeout-minutes: 15

package.json

@@ -14,7 +14,6 @@
     "@jessie.js/eslint-plugin": "^0.4.0",
     "@types/express": "^4.17.17",
     "@types/node": "^18.19.24",
-    "typescript-eslint": "^7.3.1",
     "ava": "^5.3.0",
     "c8": "^9.1.0",
     "conventional-changelog-conventionalcommits": "^4.6.0",
@@ -33,7 +32,9 @@
     "prettier-plugin-jsdoc": "^1.0.0",
     "type-coverage": "^2.27.1",
     "typedoc": "^0.25.12",
-    "typescript": "^5.4.3"
+    "typedoc-plugin-markdown": "^3.17.1",
+    "typescript": "^5.4.3",
+    "typescript-eslint": "^7.3.1"
   },
   "resolutions": {
     "**/protobufjs": "^7.2.4",
@@ -69,6 +70,7 @@
     "clean": "yarn lerna run --no-bail clean",
     "check-dependencies": "node ./scripts/check-mismatched-dependencies.cjs",
     "docs": "typedoc --tsconfig tsconfig.build.json",
+    "docs:markdown-for-agoric-documentation-repo": "typedoc --plugin typedoc-plugin-markdown --tsconfig tsconfig.build.json",
     "lerna": "lerna",
     "link-cli": "yarn run create-agoric-cli",
     "create-agoric-cli": "node ./scripts/create-agoric-cli.cjs",

packages/notifier/src/topic.js

@@ -9,7 +9,7 @@ import './types-ambient.js';
  *
  * @template T
  * @param {EachTopic<T> & LatestTopic<T>} topic needs to be near in order to
- * preserve subscription timings.  TODO: drop LatestTopic<T> requirement
+ * preserve subscription timings.  TODO: drop `LatestTopic<T>` requirement
  * @returns {EachTopic<T> & LatestTopic<T>}
  */
 export const makePinnedHistoryTopic = topic => {

packages/zoe/src/zoeService/types.js

@@ -267,7 +267,7 @@
  * The possible records are:
  * `{ waived: null }`
  * `{ onDemand: null }`
- * `{ afterDeadline: { timer :Timer<Deadline>, deadline :Deadline } }
+ * `{ afterDeadline: { timer :Timer<Deadline>, deadline :Deadline } }`
  */
 
 /**

yarn.lock

@@ -11576,6 +11576,13 @@ typedarray@^0.0.6:
   resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
   integrity sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==
 
+typedoc-plugin-markdown@^3.17.1:
+  version "3.17.1"
+  resolved "https://registry.yarnpkg.com/typedoc-plugin-markdown/-/typedoc-plugin-markdown-3.17.1.tgz#c33f42363c185adf842f4699166015f7fe0ed02b"
+  integrity sha512-QzdU3fj0Kzw2XSdoL15ExLASt2WPqD7FbLeaqwT70+XjKyTshBnUlQA5nNREO1C2P8Uen0CDjsBLMsCQ+zd0lw==
+  dependencies:
+    handlebars "^4.7.7"
+
 typedoc@^0.25.12:
   version "0.25.12"
   resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.25.12.tgz#f73f0a8d3731d418cc604d4230f95a857799e27a"