add docs

lib/babel-options-util.js

@@ -407,6 +407,26 @@ function _shouldIncludeDecoratorPlugins(config) {
   return customOptions.disableDecoratorTransforms !== true;
 }
 
+/**
+ * Returns whether we should handle TypeScript (based on the existence of
+ * `ember-cli-typescript` as a depenency). It's worth noting that we parse
+ * the `package.json` deps/devDeps directly (rather than using `addons` on
+ * the parent) because it's possible for `ember-cli-typescript` not to exist
+ * on the addons array, even if it is a dependency.
+ *
+ * Some more context:
+ *
+ * `ember-cli-typescript` returns a stable cache key so its possible for it to
+ * be deduped as part of `ember-engines`. The reason this is important is because
+ * `ember-engines` dedupe is _stateful_ so it's possible for `ember-cli-typescript`
+ * to not be part of the addons array when `ember-cli-babel` is running.
+ * 
+ * For more info on `ember-engines` dedupe logic:
+ * https://github.com/ember-engines/ember-engines/blob/master/packages/ember-engines/lib/utils/deeply-non-duplicated-addon.js#L35
+ *
+ * @name _shouldHandleTypeScript
+ * @returns {boolean}
+ */
 function _shouldHandleTypeScript(config, parent, project) {
   let emberCLIBabelConfig = config["ember-cli-babel"] || {};
 
@@ -422,6 +442,8 @@ function _shouldHandleTypeScript(config, parent, project) {
 
   let dependencies;
 
+  // consider `dependencies` and `devDependencies` if the parent is the project
+  // (`ember-cli` uses both in this case), otherwise only care about `dependencies`
   if (parent === project) {
     dependencies = Object.assign({}, pkg.dependencies, pkg.devDependencies);
   } else {