Add doc comments (#31)

* Add doc comments

* Add doc comments for the ReporterFacade class

src/artifacts/CircuitArtifacts.ts

@@ -19,6 +19,13 @@ import {
   ICircuitArtifacts,
 } from "../types/artifacts/circuit-artifacts";
 
+/**
+ * A class for easily managing circuit artifacts, including retrieving existing artifacts,
+ * creating new ones, and removing outdated artifacts.
+ *
+ * This class simplifies the process of handling circuit-related artifacts by providing
+ * methods for fetching, generating, and cleaning up artifacts that are no longer needed.
+ */
 export class CircuitArtifacts implements ICircuitArtifacts {
   // Undefined means that the cache is disabled.
   private _cache?: ArtifactsCache = {
@@ -27,13 +34,27 @@ export class CircuitArtifacts implements ICircuitArtifacts {
 
   constructor(private readonly _artifactsPath: string) {}
 
+  /**
+   * Retrieves a {@link CircuitArtifact} object based on the provided short name or fully qualified name
+   *
+   * @param circuitNameOrFullyQualifiedName The short circuit name or the fully qualified circuit name
+   *    (refer to: {@link getCircuitFullyQualifiedName} for more details)
+   * @returns A promise that resolves to the {@link CircuitArtifact} object corresponding to the provided name
+   */
   public async readCircuitArtifact(circuitNameOrFullyQualifiedName: string): Promise<CircuitArtifact> {
     const artifactPath = await this._getArtifactPath(circuitNameOrFullyQualifiedName);
     const fileContent = fsExtra.readFileSync(artifactPath, "utf-8");
 
     return JSON.parse(fileContent) as CircuitArtifact;
   }
 
+  /**
+   * Checks if a circuit artifact exists for the given short or fully qualified name
+   *
+   * @param circuitNameOrFullyQualifiedName The short circuit name or the fully qualified circuit name
+   *    (refer to: {@link getCircuitFullyQualifiedName} for more details)
+   * @returns A promise that resolves to `true` if the {@link CircuitArtifact} exists, `false` otherwise
+   */
   public async circuitArtifactExists(circuitNameOrFullyQualifiedName: string): Promise<boolean> {
     let artifactPath;
     try {
@@ -49,11 +70,22 @@ export class CircuitArtifacts implements ICircuitArtifacts {
     return fsExtra.pathExists(artifactPath);
   }
 
+  /**
+   * Retrieves an array of all fully qualified circuit names for paths discovered by the
+   * {@link getCircuitArtifactPaths} function
+   *
+   * @returns A promise that resolves to an array of fully qualified circuit names
+   */
   public async getAllCircuitFullyQualifiedNames(): Promise<string[]> {
     const paths = await this.getCircuitArtifactPaths();
     return paths.map((p) => this._getFullyQualifiedNameFromPath(p)).sort();
   }
 
+  /**
+   * Retrieves an array of all circuit artifact paths found within the artifacts directory
+   *
+   * @returns A promise that resolves to an array of circuit artifact paths
+   */
   public async getCircuitArtifactPaths(): Promise<string[]> {
     const cached = this._cache?.artifactPaths;
     if (cached !== undefined) {
@@ -69,20 +101,53 @@ export class CircuitArtifacts implements ICircuitArtifacts {
     return paths;
   }
 
+  /**
+   * Constructs and returns the full path to the artifact file using the fully qualified circuit name
+   *
+   * @param fullyQualifiedName The fully qualified circuit name
+   *    (refer to: {@link getCircuitFullyQualifiedName} for details)
+   * @returns The full path to the corresponding circuit artifact file
+   */
   public formCircuitArtifactPathFromFullyQualifiedName(fullyQualifiedName: string): string {
     const { sourceName, circuitName } = this._parseCircuitFullyQualifiedName(fullyQualifiedName);
 
     return path.join(this._artifactsPath, sourceName, `${circuitName}${CIRCUIT_ARTIFACTS_SUFFIX}`);
   }
 
+  /**
+   * Constructs and returns the fully qualified circuit name based on the provided source name and circuit template name
+   *
+   * @example
+   * // Example usage:
+   * const qualifiedName = getCircuitFullyQualifiedName("exampleSource", "exampleCircuit");
+   * console.log(qualifiedName); // Output: "exampleSource:exampleCircuit"
+   *
+   * @param sourceName The name of the source file for the circuit
+   * @param circuitName The name of the circuit template
+   * @returns The fully qualified circuit name in the format "sourceName:circuitName"
+   */
   public getCircuitFullyQualifiedName(sourceName: string, circuitName: string): string {
     return `${sourceName}:${circuitName}`;
   }
 
+  /**
+   * Retrieves the configured full path to the artifacts directory
+   *
+   * @returns The full path to the artifacts directory as a string
+   */
   public getCircuitArtifactsDirFullPath(): string {
     return this._artifactsPath;
   }
 
+  /**
+   * Constructs and returns the full path for a specific artifact file based on the provided
+   * {@link CircuitArtifact} object and the specified {@link ArtifactsFileType | file type}
+   *
+   * @param circuitArtifact The {@link CircuitArtifact} object representing the artifact
+   * @param fileType The {@link ArtifactsFileType | file type} indicating the type of artifact file
+   *    for which to retrieve the path
+   * @returns The full path of the specified artifact file associated with the provided {@link CircuitArtifact} object
+   */
   public getCircuitArtifactFileFullPath(circuitArtifact: CircuitArtifact, fileType: ArtifactsFileType): string {
     return path.join(
       this._artifactsPath,
@@ -91,6 +156,14 @@ export class CircuitArtifacts implements ICircuitArtifacts {
     );
   }
 
+  /**
+   * Saves the provided {@link CircuitArtifact} object to the artifacts file
+   *
+   * @param circuitArtifact The {@link CircuitArtifact} object to be saved
+   * @param updatedFileTypes An array of {@link ArtifactsFileType | file types} that have been modified
+   *    during the most recent session, such as during compilation
+   * @returns A promise that resolves once the save operation is complete
+   */
   public async saveCircuitArtifact(circuitArtifact: CircuitArtifact, updatedFileTypes: ArtifactsFileType[]) {
     const fullyQualifiedName = this.getCircuitFullyQualifiedName(
       circuitArtifact.circuitSourceName,
@@ -99,6 +172,7 @@ export class CircuitArtifacts implements ICircuitArtifacts {
 
     const artifactPath = this.formCircuitArtifactPathFromFullyQualifiedName(fullyQualifiedName);
 
+    // Updates the data for files that have been recently modified
     for (const fileType of updatedFileTypes) {
       const fileSourcePath: string = this.getCircuitArtifactFileFullPath(circuitArtifact, fileType);
 
@@ -114,6 +188,9 @@ export class CircuitArtifacts implements ICircuitArtifacts {
     await fsExtra.writeJSON(artifactPath, circuitArtifact, { spaces: 2 });
   }
 
+  /**
+   * Clears the local cache of artifacts
+   */
   public clearCache() {
     if (this._cache === undefined) {
       return;
@@ -124,6 +201,9 @@ export class CircuitArtifacts implements ICircuitArtifacts {
     };
   }
 
+  /**
+   * Disables the local cache of artifacts
+   */
   public disableCache() {
     this._cache = undefined;
   }

src/cache/CircuitsCompileCache.ts

@@ -8,14 +8,39 @@ import { CompileCache, CompileCacheEntry } from "../types/cache";
 import { CompileFlags } from "../types/core";
 import { Reporter } from "../reporter";
 
+/**
+ * Class that implements the caching logic for compiling circuits.
+ *
+ * This class is responsible for managing the cache of compiled circuit information,
+ * optimizing the compilation process by storing previously compiled data.
+ * It allows for a feature that avoids recompiling circuits that have not changed
+ * since the last compilation, significantly reducing unnecessary compilation overhead.
+ *
+ * The class provides methods to clear, disable, and retrieve cached artifacts,
+ * ensuring that only up-to-date and relevant information is used during compilation.
+ *
+ * The caching mechanism enhances performance and efficiency, especially when dealing
+ * with large and complex circuit designs by minimizing redundant compilation efforts.
+ */
 class BaseCircuitsCompileCache {
+  /**
+   * Creates an instance of {@link BaseCircuitsCompileCache} with empty cache data
+   *
+   * @returns An instance of {@link BaseCircuitsCompileCache} initialized with empty cache data
+   */
   public static createEmpty(): BaseCircuitsCompileCache {
     return new BaseCircuitsCompileCache({
       _format: CIRCUIT_COMPILE_CACHE_VERSION,
       files: {},
     });
   }
 
+  /**
+   * Creates an instance of {@link BaseCircuitsCompileCache} using the data read from the specified cache file
+   *
+   * @param circuitsCompileCachePath The full path to the compile cache file from which to read the data
+   * @returns A promise that resolves to an instance of {@link BaseCircuitsCompileCache} populated with the read data
+   */
   public static async readFromFile(circuitsCompileCachePath: string): Promise<BaseCircuitsCompileCache> {
     let cacheRaw: CompileCache = {
       _format: CIRCUIT_COMPILE_CACHE_VERSION,
@@ -34,6 +59,7 @@ class BaseCircuitsCompileCache {
       });
     }
 
+    // Validate the correctness of the data read from the file using the Zod schema
     const result = CompileCacheSchema.safeParse(cacheRaw);
 
     if (result.success) {
@@ -53,6 +79,12 @@ class BaseCircuitsCompileCache {
 
   constructor(private _compileCache: CompileCache) {}
 
+  /**
+   * Removes cache entries for files that no longer exist.
+   *
+   * This method helps keep the cache up-to-date by deleting references
+   * to non-existent files, ensuring that the cache remains valid.
+   */
   public async removeNonExistingFiles() {
     await Promise.all(
       Object.keys(this._compileCache.files).map(async (absolutePath) => {
@@ -63,6 +95,11 @@ class BaseCircuitsCompileCache {
     );
   }
 
+  /**
+   * Writes the current cache state to the specified file
+   *
+   * @param circuitsCompileCachePath The full path to the compile cache file where the cache will be saved
+   */
   public async writeToFile(circuitsCompileCachePath: string) {
     fsExtra.outputFileSync(
       circuitsCompileCachePath,
@@ -76,22 +113,57 @@ class BaseCircuitsCompileCache {
     );
   }
 
+  /**
+   * Adds a file cache entry to the cache data using the specified absolute path
+   *
+   * @param absolutePath The absolute path to the circuit file
+   * @param entry The cache entry to be added for the specified file path
+   */
   public addFile(absolutePath: string, entry: CompileCacheEntry) {
     this._compileCache.files[absolutePath] = entry;
   }
 
+  /**
+   * Returns all stored cache entries
+   *
+   * @returns An array of all stored cache entries
+   */
   public getEntries(): CompileCacheEntry[] {
     return Object.values(this._compileCache.files);
   }
 
+  /**
+   * Returns the cache entry for the specified file path, or undefined if no entry exists
+   *
+   * @param file The absolute path to the circuit file
+   * @returns The stored cache entry or undefined if no entry is found
+   */
   public getEntry(file: string): CompileCacheEntry | undefined {
     return this._compileCache.files[file];
   }
 
+  /**
+   * Removes the cache entry for the specified file path from the cache
+   *
+   * @param file The absolute path to the circuit file
+   */
   public removeEntry(file: string) {
     delete this._compileCache.files[file];
   }
 
+  /**
+   * Checks if the specified file has changed since the last check based on its content hash and compile flags.
+   *
+   * This method compares the current state of the file, identified by its absolute path,
+   * with the provided content hash and compile flags. If any of these values differ from
+   * what was recorded previously, the method returns true, indicating that the file has
+   * been modified. Otherwise, it returns false.
+   *
+   * @param absolutePath The absolute path of the file to compare
+   * @param contentHash The hash of the file content for comparison, used to detect changes
+   * @param compileFlags The {@link CompileFlags | compile flags} for comparison, which may affect the file's state
+   * @returns True if the file has changed since the last check, false otherwise
+   */
   public hasFileChanged(absolutePath: string, contentHash: string, compileFlags: CompileFlags): boolean {
     const cacheEntry = this.getEntry(absolutePath);
 
@@ -111,8 +183,23 @@ class BaseCircuitsCompileCache {
   }
 }
 
+/**
+ * Singleton object that serves as the cache for compilation information related to circuits.
+ *
+ * This cache holds the state of the compilation process and allows for efficient reuse
+ * of previously compiled data, thereby avoiding unnecessary recompilation of unchanged circuits.
+ *
+ * To create and properly initialize this cache object, the {@link createCircuitsCompileCache}
+ * function must be invoked. The cache can help improve performance and manage resources effectively
+ * during circuit compilation.
+ */
 export let CircuitsCompileCache: BaseCircuitsCompileCache | null = null;
 
+/**
+ * Creates a singleton instance of the {@link BaseCircuitsCompileCache} class
+ *
+ * @param circuitsCompileCachePath The full path to the compile cache file
+ */
 export async function createCircuitsCompileCache(circuitsCompileCachePath?: string) {
   if (CircuitsCompileCache) {
     return;
@@ -126,7 +213,7 @@ export async function createCircuitsCompileCache(circuitsCompileCachePath?: stri
 }
 
 /**
- * Used only in test environments to ensure test atomicity
+ * @remark Used only in test environments to ensure test atomicity
  */
 export function resetCircuitsCompileCache() {
   CircuitsCompileCache = null;