Improve documentation

Author: gitKrystan

transforms/ember-object/__testfixtures__/decorators.output.js

@@ -78,7 +78,7 @@ class Foo1 extends EmberObject {
     // class's actions to be safe. This should be refactored to call a normal method
     // on the parent class. If the parent class has not been converted to native
     // classes, it may need to be refactored as well. See
-    // https: //github.com/scalvert/ember-native-class-codemod/blob/master/README.md
+    // https://github.com/scalvert/ember-native-class-codemod/blob/master/README.md
     // for more details.
     super.actions.baz.call(this, ...arguments);
   }

transforms/ember-object/__testfixtures__/runtime.output.js

@@ -85,7 +85,7 @@ export default class _Runtime extends Runtime.extend(MyMixin) {
     // class's actions to be safe. This should be refactored to call a normal method
     // on the parent class. If the parent class has not been converted to native
     // classes, it may need to be refactored as well. See
-    // https: //github.com/scalvert/ember-native-class-codemod/blob/master/README.md
+    // https://github.com/scalvert/ember-native-class-codemod/blob/master/README.md
     // for more details.
     super.actions.overriddenActionMethod.call(this, ...arguments) && this.boolProp;
   }

transforms/helpers/ast.ts

@@ -74,6 +74,9 @@ function isIdent(u: unknown, ...names: string[]): u is Identifier {
   return isNode(u, 'Identifier') && names.includes(u.name);
 }
 
+/**
+ * A CallExpression following the `EmberObject.extend(Mixin, {})` pattern.
+ */
 export interface EOExtendExpression extends CallExpression {
   callee: EOExtendExpressionCallee;
   arguments: EOExtendArg[];
@@ -124,6 +127,10 @@ function isEOExtendExpressionCalleeProperty(
   return isIdent(u, 'extend');
 }
 
+/**
+ * The ObjectExpression argument from the `EmberObject.extend(Mixin, {})`
+ * pattern.
+ */
 export interface EOExpression extends ObjectExpression {
   properties: EOExpressionProp[];
 }
@@ -146,7 +153,7 @@ function isEOMixin(u: unknown): u is EOMixin {
   return isNode(u, 'Identifier');
 }
 
-/** A top-level instance property in an Ember Object's ObjectExpression */
+/** A top-level instance property in an EOExpression */
 export interface EOProp extends ObjectProperty {
   key: Identifier;
 }
@@ -155,7 +162,7 @@ function isEOProp(u: unknown): u is EOProp {
   return isNode(u, 'ObjectProperty') && isNode(u.key, 'Identifier');
 }
 
-/** A top-level instance property in an Ember Object's ObjectExpression */
+/** A top-level instance method in an EOExpression */
 export interface EOMethod extends ObjectMethod {
   key: Identifier;
 }
@@ -164,6 +171,10 @@ export function isEOMethod(u: unknown): u is EOMethod {
   return isNode(u, 'ObjectMethod') && isNode(u.key, 'Identifier');
 }
 
+/**
+ * A top-level instance property in an EOExpression where the value is a
+ * `FunctionExpression`.
+ */
 export interface EOFunctionExpressionProp extends EOProp {
   value: FunctionExpression;
 }
@@ -174,15 +185,22 @@ export function isEOFunctionExpressionProp(
   return isEOProp(u) && isNode(u.value, 'FunctionExpression');
 }
 
-export interface EOCallExpressionProp extends EOProp {
+/**
+ * A top-level instance property in an EOExpression where the value is a
+ * `CallExpression`. These represent computed properties.
+ */
+export interface EOComputedProp extends EOProp {
   value: EOCallExpression;
 }
 
-export function isEOCallExpressionProp(u: unknown): u is EOCallExpressionProp {
+export function isEOCallExpressionProp(u: unknown): u is EOComputedProp {
   return isEOProp(u) && isEOCallExpression(u.value);
 }
 
-/** A CallExpression value for an EOProperty */
+/**
+ * A top-level instance property in an EOExpression where the value is a
+ * `CallExpression`.
+ */
 export interface EOCallExpression extends CallExpression {
   callee: EOCallExpressionCallee;
 }
@@ -217,7 +235,10 @@ export function isEOCallExpressionInnerCallee(
   return isNode(u, 'CallExpression') && isNode(u.callee, 'Identifier');
 }
 
-/** An EOProperty that should be transformed into a class decorator */
+/**
+ * A top-level instance property in an EOExpression that should be transformed
+ * into a class decorator.
+ */
 export interface EOClassDecoratorProp extends EOProp {
   value: EOClassDecoratorValue;
   key: EOClassDecoratorKey;
@@ -245,6 +266,10 @@ function isEOClassDecoratorKey(u: unknown): u is EOClassDecoratorKey {
   return isIdent(u, ...CLASS_DECORATOR_NAMES);
 }
 
+/**
+ * A top-level instance property in an EOExpression representing the `actions`
+ * object.
+ */
 export interface EOActionsProp extends EOProp {
   value: EOActionsObjectExpression;
   key: EOActionsObjectKey;
@@ -274,12 +299,19 @@ function isEOAction(u: unknown): u is EOAction {
   return isEOActionMethod(u) || isEOActionProp(u);
 }
 
+/**
+ * An instance property in an EOActionsProp representing a method-style action.
+ */
 type EOActionMethod = EOMethod;
 
 export function isEOActionMethod(u: unknown): u is EOActionMethod {
   return isEOMethod(u);
 }
 
+/**
+ * An instance property in an EOActionsProp representing an identifier-style
+ * action.
+ */
 export interface EOActionProp extends EOProp {
   value: Identifier;
 }
@@ -296,6 +328,10 @@ function isEOActionsObjectKey(u: unknown): u is EOActionsObjectKey {
   return isIdent(u, ACTIONS_NAME);
 }
 
+/**
+ * A top-level instance property in an EOExpression representing a simple
+ * Property (typically a primitive).
+ */
 export interface EOSimpleProp extends EOProp {
   value: Exclude<
     EOProp['value'],
@@ -323,7 +359,11 @@ interface EOActionInfiniteCall extends CallExpression {
   callee: EOActionInfiniteCallCallee;
 }
 
-export function makeEOActionInfiniteCallAssertion(
+/**
+ * Makes a type predicate to check for an action that would call itself once
+ * transformed, resulting in an infinite loop.
+ */
+export function makeEOActionInfiniteCallPredicate(
   name: string
 ): (u: unknown) => u is EOActionInfiniteCall {
   return function isEOActionInfiniteCallForName(
@@ -363,7 +403,11 @@ interface EOActionInfiniteLiteral extends StringLiteral {
   value: string;
 }
 
-export function makeEOActionInfiniteLiteralAssertion(
+/**
+ * Makes a type predicate to check for an action that would call itself once
+ * transformed, resulting in an infinite loop.
+ */
+export function makeEOActionInfiniteLiteralPredicate(
   name: string
 ): (u: unknown) => u is EOActionInfiniteLiteral {
   return function isEOActionInfiniteLiteralForName(
@@ -400,7 +444,10 @@ export interface DecoratorImportDeclaration extends ImportDeclaration {
   source: StringLiteral;
 }
 
-export function makeDecoratorImportDeclarationAssertion(
+/**
+ * Makes a type predicate to find an import declaration with the given name.
+ */
+export function makeDecoratorImportDeclarationPredicate(
   path: string
 ): (u: unknown) => u is DecoratorImportDeclaration {
   return function isDecoratorImportDeclarationForPath(

transforms/helpers/decorator-helper.ts

@@ -15,7 +15,7 @@ export function createClassDecorator(
   );
 }
 
-/** Create decorators which need arguments */
+/** Create decorators which need arguments. */
 export function createDecoratorWithArgs(
   decoratorName: string,
   args: Array<string | number | boolean | RegExp | null>
@@ -28,9 +28,7 @@ export function createDecoratorWithArgs(
   );
 }
 
-/**
- * Create simple decorator with given name
- */
+/** Create simple decorator with given name. */
 export function createIdentifierDecorator(
   decoratorName: string
 ): AST.Decorator {

transforms/helpers/decorator-info.ts

@@ -1,11 +1,12 @@
 import { assert } from './util/types';
-import { METHOD_DECORATORS } from './util/index';
+import { COMPUTED_DECORATOR_NAME, METHOD_DECORATORS } from './util/index';
 import type * as AST from '../helpers/ast';
 
 export interface DecoratorImportInfo {
   name: string;
   importedName?: string;
   isImportedAs?: boolean;
+  isComputedDecorator?: boolean;
   isMetaDecorator?: boolean;
   isMethodDecorator?: boolean;
   localName?: string;
@@ -40,10 +41,12 @@ export function getDecoratorImportInfo(
   }
 
   const isMethodDecorator = METHOD_DECORATORS.has(importedName);
+  const isComputedDecorator = COMPUTED_DECORATOR_NAME === importedName;
   return {
     name,
     importedName,
     isImportedAs,
+    isComputedDecorator,
     isMetaDecorator,
     isMethodDecorator,
     localName,

transforms/helpers/eo-prop/index.ts

@@ -3,10 +3,10 @@ import type { DecoratorImportInfoMap } from '../decorator-info';
 import type { Options } from '../options';
 import { assert } from '../util/types';
 import EOActionsProp from './private/actions';
-import type EOComputedFunctionExpressionProp from './private/call-expression/function-expression';
-import { makeEOCallExpressionProp } from './private/call-expression/index';
-import type EOComputedObjectExpressionProp from './private/call-expression/object-expression';
-import type EODecoratedProp from './private/call-expression/property';
+import type EOComputedFunctionExpressionProp from './private/computed/function-expression';
+import { makeEOComputedProp } from './private/computed/index';
+import type EOComputedObjectExpressionProp from './private/computed/object-expression';
+import type EOComputedProp from './private/computed/property';
 import EOClassDecorator from './private/class-decorator';
 import EOFunctionExpressionProp from './private/function-expression';
 import EOMethod from './private/method';
@@ -20,25 +20,20 @@ export type EOProp =
   | EOSimpleProp
   | EOComputedFunctionExpressionProp
   | EOComputedObjectExpressionProp
-  | EODecoratedProp
+  | EOComputedProp
   | EOFunctionExpressionProp
   | EOMethod;
 
 /**
- * Makes an object representing an Ember Object property for the given
- * Property, RuntimeData, and ImportPropDecoratorMap.
+ * Makes an object representing an Ember Object property.
  */
 export default function makeEOProp(
   eoProp: AST.EOExpressionProp,
   existingDecoratorImportInfos: DecoratorImportInfoMap,
   options: Options
 ): EOProp | EOClassDecorator {
   if (AST.isEOCallExpressionProp(eoProp)) {
-    return makeEOCallExpressionProp(
-      eoProp,
-      existingDecoratorImportInfos,
-      options
-    );
+    return makeEOComputedProp(eoProp, existingDecoratorImportInfos, options);
   } else if (AST.isEOMethod(eoProp)) {
     return new EOMethod(eoProp, options);
   } else if (AST.isEOFunctionExpressionProp(eoProp)) {

transforms/helpers/eo-prop/private/actions/index.ts

@@ -9,6 +9,44 @@ export interface Action {
   hasInfiniteLoop: boolean;
 }
 
+/**
+ * Ember Object Actions Property
+ *
+ * A wrapper object for Ember Object `actions` object properties to be
+ * transformed into a series of `ClassMethod`s with the `@action` decorator.
+ *
+ * Each action on the object is represented either by an `EOActionMethod` or
+ * `EOActionProp`.
+ *
+ * @example
+ *
+ * ```
+ * import someActionUtil from 'some/action/util';
+ *
+ * const MyObject = EmberObject.extend({
+ *   actions: {
+ *     someActionUtil,
+ *     bar() {},
+ *   }
+ * });
+ * ```
+ *
+ * transforms into:
+ *
+ * ```
+ * import someActionUtil from 'some/action/util';
+ *
+ * class MyObject extends EmberObject {
+ *   @action
+ *   someActionUtil() {
+ *     return someActionUtil.call(this, ...arguments);
+ *   }
+ *
+ *   @action
+ *   bar() {}
+ * }
+ * ```
+ */
 export default class EOActionsProp extends AbstractEOProp<
   AST.EOActionsProp,
   AST.ClassMethod[]
@@ -24,26 +62,6 @@ export default class EOActionsProp extends AbstractEOProp<
     };
   }
 
-  /**
-   * FIXME: Verify docs
-   *
-   * Create action decorators
-   * ```
-   * Converts
-   * {
-   *  actions: {
-   *    foo() {}
-   *  }
-   * }
-   * ```
-   * to
-   * ```
-   * {
-   *  @action
-   *  foo(){ }
-   * }
-   * ```
-   */
   build(): AST.ClassMethod[] {
     return this.actions.map((action) => {
       return action.build();