Add few comments to public plugin API

ark120202 · ark120202 · commit 0c18503543f2 · 2019-11-03T03:25:07.000Z
diff --git a/src/plugins.ts b/src/plugins.ts
@@ -2,6 +2,17 @@ import { Printer } from "./LuaPrinter";
 import { Visitors } from "./transformation/context";
 
 export interface Plugin {
-    printer?: Printer;
+    /**
+     * An augmentation to the map of visitors that transform TypeScript AST to Lua AST.
+     *
+     * Key is a `SyntaxKind` of a processed node.
+     */
     visitors?: Visitors;
+
+    /**
+     * A function that converts Lua AST to a string.
+     *
+     * Only one plugin can provide `printer`.
+     */
+    printer?: Printer;
 }
diff --git a/src/transformation/context/visitors.ts b/src/transformation/context/visitors.ts
@@ -145,8 +145,20 @@ export type VisitorResult<T extends ts.Node> = T extends ExpressionLikeNode
     ? lua.Block
     : OneToManyVisitorResult<lua.Node>;
 
-export type FunctionVisitor<T extends ts.Node> = (node: T, context: TransformationContext) => VisitorResult<T>;
-export type ObjectVisitor<T extends ts.Node> = { transform: FunctionVisitor<T>; priority?: number };
 export type Visitor<T extends ts.Node> = FunctionVisitor<T> | ObjectVisitor<T>;
+export type FunctionVisitor<T extends ts.Node> = (node: T, context: TransformationContext) => VisitorResult<T>;
+export type ObjectVisitor<T extends ts.Node> = {
+    transform: FunctionVisitor<T>;
+
+    /**
+     * Visitors with higher priority are called first.
+     *
+     * Higher-priority visitors can call lower ones with `context.superTransformNode`.
+     *
+     * Standard visitors have the lowest (`-Infinity`) priority.
+     */
+    priority?: number;
+};
+
 export type Visitors = { [P in keyof NodesBySyntaxKind]?: Visitor<NodesBySyntaxKind[P]> };
 export type VisitorMap = Map<ts.SyntaxKind, Array<ObjectVisitor<ts.Node>>>;
