feat(typedoc-appium-plugin): implement cross-referencing of methods

This is getting pretty close, but:

- Commands from a driver will show even w/o a `newMethodMap` or `execMethodMap`; it is able to understand that it's overriding `BaseDriver`
- It's also able to understand the associated routes
- And it's able to understand the routes even if `BaseDriver` does not implement it

Still working on the parameters display, but we have the name override working at least.

Added some docstrings in `fake-driver`, `base-driver` for testing

.prettierignore

@@ -10,3 +10,4 @@ package.json
 **/generated/**
 # generated
 packages/types/lib/appium-config.ts
+**/*.hbs

.vscode/launch.json

@@ -50,6 +50,7 @@
       "internalConsoleOptions": "openOnSessionStart",
       "name": "Typedoc",
       "program": "${workspaceFolder}/node_modules/.bin/typedoc",
+      "args": ["--logLevel", "Verbose"],
       "request": "launch",
       "skipFiles": [
         "<node_internals>/**"

.vscode/tasks.json

@@ -4,11 +4,24 @@
     {
       "type": "npm",
       "script": "dev",
-      "group": {"kind": "build", "isDefault": true},
-      "problemMatcher": ["$tsc-watch"],
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      },
+      "problemMatcher": [
+        "$tsc-watch"
+      ],
       "label": "npm: dev",
       "detail": "npm run dev",
       "isBackground": true
+    },
+    {
+      "type": "npm",
+      "script": "typedoc",
+      "problemMatcher": [],
+      "label": "npm: typedoc",
+      "detail": "typedoc --logLevel Verbose",
+      "group": "build"
     }
   ]
 }

.wallaby.js

@@ -3,24 +3,31 @@
 module.exports = (wallaby) => {
   return {
     compilers: {
-      '**/*.js': wallaby.compilers.babel(),
+      '**/*.js': wallaby.compilers.typeScript({
+        allowJs: true,
+        allowSyntheticDefaultImports: true,
+        resolveJsonModule: true,
+        isolatedModules: true,
+      }),
+      '**/*.ts?(x)': wallaby.compilers.typeScript(),
     },
     debug: true,
     env: {
       type: 'node',
     },
     files: [
-      './packages/**/*.js',
-      './packages/**/*.json',
-      '!./packages/**/build/**',
-      '!./packages/**/test/**/*-specs.js',
-      '!./packages/**/test/**/*.spec.js',
-      '!./packages/*/node_modules/**',
-      '!./packages/*/gulpfile.js',
-      '!./packages/*/scripts/**',
-      './packages/*/test/**/fixtures/**/*',
-      './babel.config.json',
-      // below this are fixtures
+      './packages/*/build/**/*',
+      './packages/*/lib/**/*.(j|t)s',
+      './packages/*/test/**/*helper*.(j|t)s',
+      './packages/*/test/**/*mock*.(j|t)s',
+      './packages/*/package.json',
+      './packages/*/tsconfig.json',
+      './config/**/*.json',
+      './packages/*/test/**/fixture?(s)/**/*',
+      {
+        instrument: false,
+        pattern: './packages/typedoc-plugin-appium/resources/**/*',
+      },
       {
         binary: true,
         pattern: './packages/support/test/unit/assets/sample_binary.plist',
@@ -33,17 +40,17 @@ module.exports = (wallaby) => {
         instrument: false,
         pattern: './packages/base-driver/static/**/*',
       },
+      '!./packages/*/test/**/*-specs.js',
+      '!./packages/*/test/**/*.e2e.spec.(j|t)s',
       '!**/local_appium_home/**',
     ],
     testFramework: 'mocha',
-    tests: ['./packages/*/test/unit/**/*.spec.js', '!**/local_appium_home/**'],
+    tests: ['./packages/*/test/unit/**/*.spec.(j|t)s', '!**/local_appium_home/**'],
     workers: {
-      restart: true,
+      // restart: true,
     },
-    setup() {
-      // This copied out of `./test/setup.js`, which uses `@babel/register`.
-      // Wallaby doesn't need `@babel/register` (and it probably makes Wallaby slow),
-      // but we need the other stuff, so here it is.
+    setup(wallaby) {
+      // copied out of `./test/setup.js`
 
       const chai = require('chai');
       const chaiAsPromised = require('chai-as-promised');
@@ -55,6 +62,9 @@ module.exports = (wallaby) => {
 
       // `should()` is only necessary when working with some `null` or `undefined` values.
       global.should = chai.should();
+
+      const mocha = wallaby.testFramework;
+      mocha.timeout(10000);
     },
     runMode: 'onsave',
   };

packages/appium/package.json

@@ -105,6 +105,6 @@
   },
   "gitHead": "5c7af8ee73078018e4ec52fccf19fe3f77249d72",
   "typedoc": {
-    "entryPoint": "./build/lib/main.js"
+    "entryPoint": "./lib/main.js"
   }
 }

packages/base-driver/lib/basedriver/capabilities.js

@@ -40,7 +40,7 @@ function mergeCaps(primary = {}, secondary = {}) {
 
 // Validates caps against a set of constraints
 /**
- * @template {Constraints} [C={}]
+ * @template {Constraints} [C=import('type-fest').EmptyObject]
  * @param {Capabilities<C>} caps
  * @param {C} [constraints]
  * @param {ValidateCapsOpts} [opts]

packages/base-driver/lib/basedriver/commands/session.js

@@ -30,6 +30,7 @@ export function SessionMixin(Base) {
     }
 
     /**
+     * Returns capabilities for the session and event history (if applicable)
      * @returns {Promise<SingularSessionData>}
      */
     async getSession() {

packages/base-driver/lib/basedriver/driver.js

@@ -414,7 +414,7 @@ export class BaseDriverCore extends DriverCore {
 
 /**
  * This ensures that all of the mixins correctly implement the interface described in {@linkcode Driver}.
- * @template {Constraints} [C={}]
+ * @template {Constraints} [C=import('type-fest').EmptyObject]
  * @implements {Driver<C>}
  */
 export class BaseDriver extends createBaseDriverClass(BaseDriverCore) {}

packages/base-driver/package.json

@@ -74,6 +74,6 @@
   },
   "gitHead": "5c7af8ee73078018e4ec52fccf19fe3f77249d72",
   "typedoc": {
-    "entryPoint": "./build/lib/index.js"
+    "entryPoint": "./lib/index.js"
   }
 }

packages/base-plugin/package.json

@@ -2,6 +2,16 @@
   "name": "@appium/base-plugin",
   "version": "2.0.1",
   "description": "The base plugin used to create Appium 2.0 plugins",
+  "keywords": [
+    "automation",
+    "javascript",
+    "selenium",
+    "webdriver",
+    "ios",
+    "android",
+    "firefoxos",
+    "testing"
+  ],
   "homepage": "https://appium.io",
   "bugs": {
     "url": "https://github.com/appium/appium/issues"
@@ -39,16 +49,6 @@
     "appium"
   ],
   "typedoc": {
-    "entryPoint": "./build/lib/plugin.js"
-  },
-  "keywords": [
-    "automation",
-    "javascript",
-    "selenium",
-    "webdriver",
-    "ios",
-    "android",
-    "firefoxos",
-    "testing"
-  ]
+    "entryPoint": "./lib/plugin.js"
+  }
 }

packages/fake-driver/lib/commands/contexts.js

@@ -26,9 +26,8 @@ export function ContextsMixin(Base) {
       }
     }
 
-    /**
-     * Get the current appium context
-     *
+    // do not add a description to this method's docstring
+    /*
      * @returns {Promise<string>}
      */
     async getCurrentContext() {

packages/fake-driver/lib/commands/element.js

@@ -64,6 +64,10 @@ export function ElementMixin(Base) {
       await this.setValue('', elementId);
     }
 
+    /**
+     * This comment should be displayed instead of the one from ExternalDriver
+     * @param {string} elementId
+     */
     async click(elementId) {
       this.assertNoAlert();
       let el = this.getElement(elementId);

packages/fake-driver/lib/commands/find.js

@@ -78,6 +78,11 @@ export function FindMixin(Base) {
       return /** @type {Mult extends true ? Element[] : Element} */ (retval);
     }
 
+    /**
+     * This should override whatever's in ExternalDriver
+     * @param {string} strategy Strategy
+     * @param {string} selector Selector
+     */
     async findElement(strategy, selector) {
       return this.findElOrEls(strategy, selector, false);
     }

packages/fake-driver/lib/commands/index.js

@@ -7,7 +7,6 @@ import {GeneralMixin} from './general';
 /**
  *
  * @param {import('@appium/types').Class<import('../driver').FakeDriverCore>} Base
- * @returns
  */
 export function FakeDriverMixin(Base) {
   return GeneralMixin(FindMixin(ElementMixin(AlertMixin(ContextsMixin(Base)))));

packages/fake-driver/lib/driver.js

@@ -65,25 +65,26 @@ export class FakeDriverCore extends BaseDriver {
   }
 
   /**
-   *
-   * @param {W3CFakeDriverCaps} jsonwpDesiredCapabilities
-   * @param {W3CFakeDriverCaps} [jsonwpRequiredCaps]
-   * @param {W3CFakeDriverCaps} [w3cCapabilities]
-   * @param {import('@appium/types').DriverData[]} [otherSessionData]
-   * @returns {Promise<[string,FakeDriverCaps]>}
+   * Comment for `createSession` in `FakeDriver`
+   * @param {W3CFakeDriverCaps} w3cCapabilities1 W3C Capabilities
+   * @param {W3CFakeDriverCaps} [w3cCapabilities2] W3C Capabilities
+   * @param {W3CFakeDriverCaps} [w3cCapabilities3] W3C Capabilities
+   * @param {import('@appium/types').DriverData[]} [driverData] Other session data
+   * @override
+   * @returns {Promise<[string,FakeDriverCaps]>} Session ID and normalized capabilities
    */
   async createSession(
-    jsonwpDesiredCapabilities,
-    jsonwpRequiredCaps,
-    w3cCapabilities,
-    otherSessionData = []
+    w3cCapabilities1,
+    w3cCapabilities2,
+    w3cCapabilities3,
+    driverData = []
   ) {
     // TODO add validation on caps.app that we will get for free from
     // BaseDriver
 
     // check to see if any other sessions have set uniqueApp. If so, emulate
     // not being able to start a session because of system resources
-    for (let d of otherSessionData) {
+    for (let d of driverData) {
       if (d.isUnique) {
         throw new errors.SessionNotCreatedError(
           'Cannot start session; another ' +
@@ -94,10 +95,10 @@ export class FakeDriverCore extends BaseDriver {
 
     let [sessionId, caps] = /** @type {[string, FakeDriverCaps]} */ (
       await super.createSession(
-        jsonwpDesiredCapabilities,
-        jsonwpRequiredCaps,
-        w3cCapabilities,
-        otherSessionData
+        w3cCapabilities1,
+        w3cCapabilities2,
+        w3cCapabilities3,
+        driverData
       )
     );
     this.caps = caps;

packages/fake-driver/lib/index.js

@@ -15,3 +15,8 @@ async function main() {
 }
 
 export {FakeDriver, startServer, main};
+
+/**
+ * @typedef {import('./types').W3CFakeDriverCaps} W3CFakeDriverCaps
+ * @typedef {import('./types').FakeDriverCaps} FakeDriverCaps
+ */

packages/fake-driver/package.json

@@ -77,7 +77,7 @@
     }
   },
   "typedoc": {
-    "entryPoint": "./build/lib/index.js"
+    "entryPoint": "./lib/index.js"
   },
   "types": "./build/lib/index.d.ts",
   "gitHead": "5c7af8ee73078018e4ec52fccf19fe3f77249d72"

packages/fake-plugin/package.json

@@ -2,6 +2,16 @@
   "name": "@appium/fake-plugin",
   "version": "3.0.1",
   "description": "A fake Appium 2.0 plugin",
+  "keywords": [
+    "automation",
+    "javascript",
+    "selenium",
+    "webdriver",
+    "ios",
+    "android",
+    "firefoxos",
+    "testing"
+  ],
   "homepage": "https://appium.io",
   "bugs": {
     "url": "https://github.com/appium/appium/issues"
@@ -13,7 +23,6 @@
   },
   "license": "Apache-2.0",
   "author": "https://github.com/appium",
-  "main": "./build/index.js",
   "directories": {
     "lib": "./lib"
   },
@@ -54,14 +63,7 @@
   "tags": [
     "appium"
   ],
-  "keywords": [
-    "automation",
-    "javascript",
-    "selenium",
-    "webdriver",
-    "ios",
-    "android",
-    "firefoxos",
-    "testing"
-  ]
+  "typedoc": {
+    "entryPoint": "./lib/plugin.js"
+  }
 }

packages/schema/package.json

@@ -47,7 +47,7 @@
     "access": "public"
   },
   "typedoc": {
-    "entryPoint": "./build/index.js"
+    "entryPoint": "./lib/index.js"
   },
   "gitHead": "5c7af8ee73078018e4ec52fccf19fe3f77249d72"
 }

packages/support/package.json

@@ -106,7 +106,7 @@
   },
   "gitHead": "5c7af8ee73078018e4ec52fccf19fe3f77249d72",
   "typedoc": {
-    "entryPoint": "./build/lib/index.js"
+    "entryPoint": "./lib/index.js"
   },
   "overrides": {
     "jpeg-js": "0.4.4"

packages/typedoc-plugin-appium/lib/converter/base-converter.ts

@@ -0,0 +1,13 @@
+import {Context} from 'typedoc';
+import {AppiumPluginLogger} from '../logger';
+import {ModuleCommands} from '../model';
+
+export abstract class BaseConverter<T> {
+  constructor(
+    protected ctx: Context,
+    protected log: AppiumPluginLogger,
+    protected readonly builtinCommands?: ModuleCommands
+  ) {}
+
+  abstract convert(): T;
+}