From 8b95c82ea41abfb1776e686a1182d48061501453 Mon Sep 17 00:00:00 2001
From: Isaac Lee <16869656+ijlee2@users.noreply.github.com>
Date: Sun, 29 Oct 2023 12:51:42 +0100
Subject: [PATCH] Added JSDoc to @codemod-utils/ast-template (#94)

* refactor: Added JSDoc to @codemod-utils/ast-template

* chore: Added changeset

---------

Co-authored-by: ijlee2 <ijlee2@users.noreply.github.com>
---
 .changeset/hot-hairs-exist.md               |  5 +++
 packages/ast/template/README.md             | 12 +++----
 packages/ast/template/src/ast/handlebars.ts | 37 +++++++++++++++------
 packages/ast/template/src/index.ts          |  2 +-
 4 files changed, 37 insertions(+), 19 deletions(-)
 create mode 100644 .changeset/hot-hairs-exist.md

diff --git a/.changeset/hot-hairs-exist.md b/.changeset/hot-hairs-exist.md
new file mode 100644
index 00000000..fdbb12cd
--- /dev/null
+++ b/.changeset/hot-hairs-exist.md
@@ -0,0 +1,5 @@
+---
+"@codemod-utils/ast-template": minor
+---
+
+Added JSDoc to @codemod-utils/ast-template
diff --git a/packages/ast/template/README.md b/packages/ast/template/README.md
index 28e3a694..8e02333e 100644
--- a/packages/ast/template/README.md
+++ b/packages/ast/template/README.md
@@ -7,14 +7,12 @@ _Utilities for handling `*.hbs` files as abstract syntax tree_
 
 ## What is it?
 
-`@codemod-utils/ast-template` wraps the methods from [`ember-template-recast`](https://github.com/ember-template-lint/ember-template-recast), a library that helps you parse and transform `*.hbs` files.
+`@codemod-utils/ast-template` provides methods from [`ember-template-recast`](https://github.com/ember-template-lint/ember-template-recast) to help you parse and transform `*.hbs` files.
 
-The wrappers help you read and write files of different types _in the same way_. This way, you can focus on learning the **builders** and **visit methods**, the building blocks for transforming code (library-dependent).
-
-```js
+```ts
 import { AST } from '@codemod-utils/ast-template';
 
-function transformCode(file) {
+function transformCode(file: string): string {
   const traverse = AST.traverse();
 
   const ast = traverse(file, {
@@ -57,7 +55,7 @@ Copy-paste the visit methods from your file to AST explorer, then rename `AST.bu
 
 <summary>Example</summary>
 
-```js
+```ts
 /* Your file */
 import { AST } from '@codemod-utils/ast-template';
 
@@ -84,7 +82,7 @@ function transformCode(file) {
 }
 ```
 
-```js
+```ts
 /* AST Explorer */
 module.exports = function(env) {
   const b = env.syntax.builders;
diff --git a/packages/ast/template/src/ast/handlebars.ts b/packages/ast/template/src/ast/handlebars.ts
index b1e4cea0..45542595 100644
--- a/packages/ast/template/src/ast/handlebars.ts
+++ b/packages/ast/template/src/ast/handlebars.ts
@@ -1,5 +1,5 @@
 import {
-  type AST,
+  type AST as _AST,
   builders,
   type NodeVisitor,
   print,
@@ -7,7 +7,10 @@ import {
 } from 'ember-template-recast';
 
 function _traverse() {
-  return function (file: string, visitMethods: NodeVisitor = {}): AST.Template {
+  return function (
+    file: string,
+    visitMethods: NodeVisitor = {},
+  ): _AST.Template {
     const { ast } = transform({
       plugin() {
         return visitMethods;
@@ -19,16 +22,28 @@ function _traverse() {
   };
 }
 
-type Tools = {
-  builders: typeof builders;
-  print: typeof print;
-  traverse: typeof _traverse;
-};
-
-const tools: Tools = {
+/**
+ * Provides methods from `ember-template-recast` to help you parse
+ * and transform `*.hbs` files.
+ *
+ * @example
+ *
+ * ```ts
+ * import { AST } from '@codemod-utils/ast-template';
+ *
+ * function transformCode(file: string): string {
+ *   const traverse = AST.traverse();
+ *
+ *   const ast = traverse(file, {
+ *     // Use AST.builders to transform the tree
+ *   });
+ *
+ *   return AST.print(ast);
+ * }
+ * ```
+ */
+export const AST = {
   builders,
   print,
   traverse: _traverse,
 };
-
-export default tools;
diff --git a/packages/ast/template/src/index.ts b/packages/ast/template/src/index.ts
index 47985f8a..cc2c0363 100644
--- a/packages/ast/template/src/index.ts
+++ b/packages/ast/template/src/index.ts
@@ -1 +1 @@
-export { default as AST } from './ast/handlebars.js';
+export * from './ast/handlebars.js';