If a command is not documented with a `@returns` tag, but a builtin method _does_ have this tag (e.g., `ExternalDriver.createSession()`), then the plugin will use the tag from the builtin.
If a command _does_ have a `@returns` tag, but it provides no description, then the plugin will use the original `@returns` tag (which may have a type) and combine it with the content/description from the builtin (if any).
This requires further inspection of `SignatureReflection` data, which needed a new set of "comment finders", which prompted me to refactor the comment finders into their own files (because it was becoming unwieldy). The call to `deriveComment` happens in the static `BaseCommandData.rewriteSignature()` method (whereas before it was just a straightforward clone operation).
- Fixed the block tag aggregation to prefer contentful over contentless tags in all cases.
- Modified the `@returns` tag of `FakeDriver.createSession()` for testing
- Moved some types around that were used outside of their sibling modules (e.g. `CommentSource` which used to be called `CommentSourceType`)
- pruned dead imports
`type-fest`@3.6.0 has a `TsConfigJson` type which no longer contains `unknown` (courtesy of yours truly), so we can use it directly instead of wrapping it in `Jsonify`.
This adds a function `startStoppableAppium()` which starts an Appium server (via its `main()` entry point), but resolves with an object having a `stop() => Promise<boolean>` method. This method force-quits the server, even if there are active connections.
I noticed we were filling up our allotted cache space. Reading about it, I found this example to cleanup caches we no longer need (specifically, from closed PRs)
for https://github.com/advisories/GHSA-rc47-6667-2j5j
this override should be removed when upgrading webdriver to v8+. unfortunately "npm audit" is so stupid that it does not understand overrides, so we will see warnings anyway.
= moves example extraction to conversion phase (from rendering phase)
- add `cloneTypeParameterReflection()` util
- add support for passing explicit comments to `deriveComment` when `refl` is a `ParameterReflection`
- some tests
In #18132, I found that parameter descriptions of commands were being omitted from the output. Those descriptions have to come from a method, because they cannot be expressed in their original location (a method map) via JS or a docstring.
In addition, if an extension's implementation did not describe the parameters (e.g., in `@param` tags), we need to pull those descriptions out of `ExternalDriver` (assuming they exist).
Furthermore, we were executing the conversion _too early_ in TypeDoc's lifecycle, since its internal plugins haven't run yet. One of those plugins actually moves the `@param` comments from the _signature_ into the appropriate parameter. Once those are there, we can find them.
- Added a new list of "comment finders" which are parameter-specific (could probably do the same thing for return statements)
- Moved some functions into different modules and renamed a couple things to be more accurate.
- Update VSCode launch config
- `CommandData` now requires a reflection of a method. This was true before, but not formalized
anything newer than v4.7.4 fails to ignore an optional arg in `@param {T} [foo]` if `foo` has a default assignment in the function signature. removing the square brackets fixes the issue.
whether or not this is a bug, I am not entirely sure: it is marked as a bug, but it is also not something the TS team is in a hurry to fix, so whatevs.
- in type `DeployOpts`, `mkDocsYml` should have been `mkdocsYml`
- arguments were only being omitted from being passed to `mike` if they were `false`, but it needed to also consider `undefined` values and empty string values. `0` is falsy, but we should not disallow this. thus... "most" falsy values get ignored.
This changes how packages get their titles (the h1 in the commands page, which is used by mkdocs in the nav bar).
A new option, `packageTitles` is available in `typedoc.json`. This is an array of objects like so:
```json
{
"packageTitles": [
{"name": "@appium/fake-driver": "title": "Fake Driver"},
{"name": "@appium/fake-plugin": "title": "Fake Plugin"}
]
}
```
This allows granular control over how each package is titled. However, if this option is not provided, the plugin will "extract" a title from the `package.json` of each package, assuming that package is an Appium extension. By default, it will name drivers `Driver: ${appium.driverName}` and plugins `Plugin: ${appium.pluginName}` where `appium` is a prop in `package.json`.
If the package is _not_ an extension but _does_ have commands -- and currently the only package that fulfills this criteria is `@appium/base-driver` -- _and_ is in a multi-package project, the title will be `${name} Commands` where `name` is from `package.json`. Otherwise, if we are documenting a project with a single package (e.g., a 3p extension) _and_ we cannot otherwise derive a title, we will just use `Commands` for the title.
Christopher Hiller