From c3f17734f064c97e86c6624433092217e5a908aa Mon Sep 17 00:00:00 2001
From: Littlegnal <8847263+littleGnAl@users.noreply.github.com>
Date: Tue, 14 Nov 2023 10:48:16 +0800
Subject: [PATCH] doc: Add more doc for terra-core (#33)

---
 terra-core/src/index.ts         | 44 ++++++++++++++++++++++++++++++++-
 terra-core/src/path_resolver.ts | 23 +++++++++++++++--
 terra-core/src/testing_utils.ts |  2 +-
 3 files changed, 65 insertions(+), 4 deletions(-)

diff --git a/terra-core/src/index.ts b/terra-core/src/index.ts
index 9bc68e0..c5796e0 100644
--- a/terra-core/src/index.ts
+++ b/terra-core/src/index.ts
@@ -1,14 +1,34 @@
-// export * from "./app_root_path";
 export * from './path_resolver';
 export * from './testing_utils';
 
+/**
+ * Abstract representation of a AST node in terra.
+ * This interface serves as a base for node types and can be extended to
+ * represent various node-specific details and functionalities within terra.
+ */
 export interface TerraNode {}
 
+/**
+ * Class representing the result of a parsing operation.
+ * Contains an array of `TerraNode` objects.
+ */
 export class ParseResult {
   nodes: TerraNode[] = [];
 }
 
+/**
+ * Represents the context in which terra operates.
+ * Includes various directory paths and configuration flags.
+ */
 export class TerraContext {
+  /**
+   * Constructs a new `TerraContext` instance.
+   * @param buildDir The build directory path.
+   * @param configDir The configuration directory path.
+   * @param outputDir The output directory path.
+   * @param clean Flag indicating whether to clean the build directory.
+   * @param verbose Flag for verbose logging.
+   */
   constructor(
     public readonly buildDir: string = '',
     public readonly configDir: string = '',
@@ -18,17 +38,39 @@ export class TerraContext {
   ) {}
 }
 
+/**
+ * Type definition for a Parser function in terra.
+ * Transforms source code into AST nodes (TerraNode).
+ * This `Parser` can be part of a chain, where each `Parser` has the ability
+ * to modify the results of its predecessor before passing them to the next `Parser`.
+ *
+ * @param terraContext The `TerraContext` instance, providing operational context.
+ * @param args Additional arguments or data for parsing.
+ * @param parseResult An optional initial `ParseResult` from a previous Parser in the chain.
+ * @returns A new or modified `ParseResult` to be used by subsequent Parsers.
+ */
 export type Parser = (
   terraContext: TerraContext,
   args: any,
   parseResult?: ParseResult
 ) => ParseResult | undefined;
 
+/** Interface representing the result of a rendering operation. */
 export interface RenderResult {
   file_name: string;
   file_content: string;
 }
 
+/**
+ * Type definition for a Renderer function in Terra.
+ * Processes the results obtained from a Parser.
+ * Use this Renderer to generate code or other forms of output based on the parsed AST nodes (TerraNode).
+ *
+ * @param terraContext The `TerraContext` instance, providing the operational context.
+ * @param args Additional arguments relevant to the rendering process.
+ * @param parseResult The `ParseResult` instance containing the Parser's output.
+ * @returns An array of `RenderResult` objects, representing the rendered output.
+ */
 export type Renderer = (
   terraContext: TerraContext,
   args: any,
diff --git a/terra-core/src/path_resolver.ts b/terra-core/src/path_resolver.ts
index 1ef33ce..50cee92 100644
--- a/terra-core/src/path_resolver.ts
+++ b/terra-core/src/path_resolver.ts
@@ -1,10 +1,15 @@
 import fs from 'fs';
 
-import os from 'os';
 import path from 'path';
 
 /**
- * Resolve the schema: `<module_name>:<path>`, or absolute path, or relative path
+ * Resolves a given path to its absolute form.
+ * It can resolve paths in various formats: module schemas (`<module_name>:<path>`), absolute paths, or relative paths.
+ * If the path is not absolute and `prefixDirIfNotAbsolute` is provided, the path is resolved relative to this directory.
+ *
+ * @param p The path to resolve, which can be in the format of a module schema, absolute, or relative path.
+ * @param prefixDirIfNotAbsolute The directory to use as a prefix for non-absolute paths. Defaults to an empty string.
+ * @returns The resolved absolute path.
  */
 export function resolvePath(
   p: string,
@@ -34,6 +39,13 @@ export function resolvePath(
   return path.resolve(localPathInModule);
 }
 
+/**
+ * Resolves the path to a specified module.
+ * This function assumes the module exists in the `node_modules` directory relative to the current package's `package.json`.
+ *
+ * @param module The name of the module to resolve.
+ * @returns The resolved path of the module.
+ */
 // TODO(littlegnal): Use `require.resolve(`${module}/package.json`)` to require the module's path
 export function resolveModulePath(module: string): string {
   let currentPackageJsonPath = process.env.npm_package_json;
@@ -49,6 +61,13 @@ export function resolveModulePath(module: string): string {
   return path.resolve(parserPackageDir);
 }
 
+/**
+ * Requires a module and returns its exported content.
+ * The module is expected to be located in the `node_modules` directory relative to the current package's `package.json`.
+ *
+ * @param module The name of the module to require.
+ * @returns The exported content of the required module.
+ */
 // TODO(littlegnal): Use `require(`${module}/package.json`)` to require the module
 export function requireModule(module: string): any {
   let currentPackageJsonPath = process.env.npm_package_json;
diff --git a/terra-core/src/testing_utils.ts b/terra-core/src/testing_utils.ts
index 96f7f2e..db6dd87 100644
--- a/terra-core/src/testing_utils.ts
+++ b/terra-core/src/testing_utils.ts
@@ -34,4 +34,4 @@ export function visibleForTesting(module: any, ...func: Function[]): void {
       }
     }
   }
-}
\ No newline at end of file
+}