Switch to typedoc for documentation (matrix-org#2869)

This seems to give *much* better results than jsdoc, and means that we can
start to get rid of all the duplicated type information.

.github/workflows/release.yml

@@ -24,10 +24,7 @@ jobs:
 
       - name: 📋 Copy to temp
         run: |
-          tag="${{ github.ref_name }}"
-          version="${tag#v}"
-          echo "VERSION=$version" >> $GITHUB_ENV
-          cp -a "./.jsdoc/matrix-js-sdk/$version" $RUNNER_TEMP
+          cp -a "./_docs" "$RUNNER_TEMP/"
 
       - name: 🧮 Checkout gh-pages
         uses: actions/checkout@v3
@@ -36,7 +33,10 @@ jobs:
 
       - name: 🔪 Prepare
         run: |
-          cp -a "$RUNNER_TEMP/$VERSION" .
+          tag="${{ github.ref_name }}"
+          VERSION="${tag#v}"
+          [ ! -e "$VERSION" ] || rm -r $VERSION
+          cp -r $RUNNER_TEMP/docs/ $VERSION
 
           # Add the new directory to the index if it isn't there already
           if ! grep -q ">Version $VERSION</a>" index.html; then

.github/workflows/static_analysis.yml

@@ -63,7 +63,7 @@ jobs:
         run: "yarn install"
 
       - name: Generate Docs
-        run: "yarn run gendoc -d _docs"
+        run: "yarn run gendoc"
 
       - name: Upload Artifact
         uses: actions/upload-artifact@v2

.gitignore

@@ -1,5 +1,4 @@
-/.jsdocbuild
-/.jsdoc
+/_docs
 .DS_Store
 
 node_modules

README.md

@@ -295,12 +295,12 @@ API Reference
 A hosted reference can be found at
 http://matrix-org.github.io/matrix-js-sdk/index.html
 
-This SDK uses JSDoc3 style comments. You can manually build and
+This SDK uses [Typedoc](https://typedoc.org/guides/doccomments) doc comments. You can manually build and
 host the API reference from the source files like this:
 
 ```
   $ yarn gendoc
-  $ cd .jsdoc
+  $ cd _docs
   $ python -m http.server 8005
 ```
 

package.json

@@ -16,7 +16,7 @@
     "build:compile": "babel -d lib --verbose --extensions \".ts,.js\" src",
     "build:compile-browser": "mkdirp dist && browserify -d src/browser-index.js -p [ tsify -p ./tsconfig-build.json ] -t [ babelify --sourceMaps=inline --presets [ @babel/preset-env @babel/preset-typescript ] ] | exorcist dist/browser-matrix.js.map > dist/browser-matrix.js",
     "build:minify-browser": "terser dist/browser-matrix.js --compress --mangle --source-map --output dist/browser-matrix.min.js",
-    "gendoc": "jsdoc -c jsdoc.json -P package.json",
+    "gendoc": "typedoc",
     "lint": "yarn lint:types && yarn lint:js",
     "lint:js": "eslint --max-warnings 0 src spec",
     "lint:js-fix": "eslint --fix src spec",
@@ -107,11 +107,12 @@
     "jest-environment-jsdom": "^28.1.3",
     "jest-localstorage-mock": "^2.4.6",
     "jest-mock": "^29.0.0",
-    "jsdoc": "^3.6.6",
     "matrix-mock-request": "^2.5.0",
     "rimraf": "^3.0.2",
     "terser": "^5.5.1",
     "tsify": "^5.0.2",
+    "typedoc": "^0.23.20",
+    "typedoc-plugin-missing-exports": "^1.0.0",
     "typescript": "^4.5.3"
   },
   "jest": {

tsconfig.json

@@ -14,5 +14,10 @@
   "include": [
     "./src/**/*.ts",
     "./spec/**/*.ts"
-  ]
+  ],
+  "typedocOptions": {
+    "entryPoints": ["src/index.ts"],
+    "excludeExternals": true,
+    "out": "_docs"
+  }
 }