@appium/typedoc-plugin-appium
Version:
TypeDoc plugin for Appium & its extensions
138 lines • 6.34 kB
JavaScript
;
/**
* A thing that creates {@linkcode typedoc#DeclarationReflection} instances from parsed
* command & execute method data.
* @module
*/
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.omitBuiltinReflections = exports.omitDefaultReflections = exports.createReflections = exports.createExtensionReflection = exports.createCommandReflection = void 0;
const lodash_1 = __importDefault(require("lodash"));
const pluralize_1 = __importDefault(require("pluralize"));
const guards_1 = require("../guards");
const model_1 = require("../model");
const builtin_method_map_1 = require("./builtin-method-map");
const utils_1 = require("./utils");
/**
* Creates and adds a child {@linkcode CommandReflection} to this reflection
*
* During "normal" usage of TypeDoc, one would call
* `createDeclarationReflection()`. But since we've subclassed
* `DeclarationReflection`, we cannot call it directly. It doesn't seem to do
* anything useful besides instantiation then delegating to
* `postReflectionCreation()`; so we just need to call it directly.
*
* Finally, we call `finalizeDeclarationReflection()` which I think just fires
* some events for other plugins to potentially use.
* @param log Logger
* @param data Command reference
* @param route Route
* @param parent Commands reflection
* @internal
*/
function createCommandReflection(ctx, data, parent, route) {
const commandRefl = new model_1.CommandReflection(data, parent, route);
// yes, the `undefined`s are needed
ctx.postReflectionCreation(commandRefl, undefined, undefined);
ctx.finalizeDeclarationReflection(commandRefl);
}
exports.createCommandReflection = createCommandReflection;
/**
* Create a new {@linkcode ExtensionReflection} and all {@linkcode CommandReflection} children within
* it.
*
* Note that the return value is mainly for informational purposes, since this method mutates
* TypeDoc's state.
* @param log - Logger
* @param ctx - Context
* @param name - Name of module containing commands
* @param moduleCmds - Command information for `module`
* @internal
*/
function createExtensionReflection(log, ctx, name, moduleCmds) {
const packageTitles = ctx.converter.application.options.getValue('packageTitles');
log.verbose(`Value of packageTitles: %O`, packageTitles);
// TODO: parent.name may not be right here
const extRefl = new model_1.ExtensionReflection(name, ctx.project, moduleCmds, packageTitles.find((p) => p.name === name)?.title);
/**
* See note in {@link createCommandReflection} above about this call
*/
ctx.postReflectionCreation(extRefl, undefined, undefined);
const parentCtx = ctx.withScope(extRefl);
const { routeMap: routeMap, execMethodDataSet: execCommandsData } = moduleCmds;
for (const [route, commandSet] of routeMap) {
for (const data of commandSet) {
createCommandReflection(parentCtx, data, extRefl, route);
}
}
for (const data of execCommandsData) {
createCommandReflection(parentCtx, data, extRefl);
}
ctx.finalizeDeclarationReflection(extRefl);
return extRefl;
}
exports.createExtensionReflection = createExtensionReflection;
/**
* Creates custom {@linkcode typedoc#DeclarationReflection}s from parsed command & execute method data.
*
* These instances are added to the {@linkcode Context} object itself; this mutates TypeDoc's internal state. Nothing is returned.
* @param ctx TypeDoc Context
* @param parentLog Plugin logger
* @param projectCmds Command info from converter; a map of parent reflections to parsed data
* @returns List of {@linkcode ExtensionReflection} instances
*/
function createReflections(ctx, parentLog, projectCmds) {
const log = parentLog.createChildLogger('builder');
const { project } = ctx;
if (!projectCmds.size) {
log.error('No reflections to create; nothing to do.');
return [];
}
return [...projectCmds.entries()].map(([parentName, parentCmds]) => {
const parentRefl = project.name === parentName
? project
: (0, utils_1.findChildByNameAndGuard)(project, parentName, guards_1.isParentReflection);
const cmdsRefl = createExtensionReflection(log, ctx, parentRefl.name, parentCmds);
log.info('(%s) Created %d new command %s', parentName, cmdsRefl.children?.length ?? 0, (0, pluralize_1.default)('reflection', cmdsRefl.children?.length ?? 0));
return cmdsRefl;
});
}
exports.createReflections = createReflections;
/**
* Removes any reflection _not_ created by this plugin from the TypeDoc refl _except_ those
* created by this plugin.
* @param project - Current TypeDoc project
* @param refl - A {@linkcode ContainerReflection} to remove children from; defaults to `project`
* @returns A set of removed {@linkcode DeclarationReflection DeclarationReflections}
*/
function omitDefaultReflections(project, refl = project) {
const removed = new Set();
for (const childRefl of refl.getChildrenByKind(~model_1.AppiumPluginReflectionKind.Extension)) {
project.removeReflection(childRefl);
removed.add(childRefl);
}
return removed;
}
exports.omitDefaultReflections = omitDefaultReflections;
/**
* Removes extension reflection(s) which are part of Appium itself. This is desirable for most
* extension authors.
* @param project - Current TypeDoc project
* @param refl - A {@linkcode ContainerReflection} to remove children from; defaults to `project`
* @returns A set of removed {@linkcode DeclarationReflection}s
*/
function omitBuiltinReflections(project, refl = project) {
const removed = new Set();
const extRefls = refl.getChildrenByKind(model_1.AppiumPluginReflectionKind.Extension);
const builtinRefl = lodash_1.default.find(extRefls, { name: builtin_method_map_1.NAME_BUILTIN_COMMAND_MODULE });
if (!builtinRefl) {
throw new Error(`Could not find builtin commands reflection "${builtin_method_map_1.NAME_BUILTIN_COMMAND_MODULE}"`);
}
project.removeReflection(builtinRefl);
removed.add(builtinRefl);
return removed;
}
exports.omitBuiltinReflections = omitBuiltinReflections;
//# sourceMappingURL=builder.js.map