chore: add comments documenting public API

etc/fiddle-core.api.md

@@ -15,112 +15,77 @@ import { Writable } from 'stream';
 // @public
 export class BaseVersions implements Versions {
     constructor(versions: unknown);
-    // (undocumented)
     getReleaseInfo(ver: SemOrStr): ReleaseInfo | undefined;
-    // (undocumented)
     inMajor(major: number): SemVer[];
-    // (undocumented)
     inRange(a: SemOrStr, b: SemOrStr): SemVer[];
-    // (undocumented)
     isVersion(ver: SemOrStr): boolean;
-    // (undocumented)
     get latest(): SemVer | undefined;
-    // (undocumented)
     get latestStable(): SemVer | undefined;
-    // (undocumented)
     get obsoleteMajors(): number[];
-    // (undocumented)
     get prereleaseMajors(): number[];
-    // (undocumented)
     protected setVersions(val: unknown): void;
-    // (undocumented)
     get stableMajors(): number[];
-    // (undocumented)
     get supportedMajors(): number[];
-    // (undocumented)
     get versions(): SemVer[];
 }
 
-// @public (undocumented)
+// @public
 export interface BisectResult {
-    // (undocumented)
     range?: [string, string];
-    // (undocumented)
     status: 'bisect_succeeded' | 'test_error' | 'system_error';
 }
 
-// @public (undocumented)
+// @public
 export function compareVersions(a: SemVer, b: SemVer): number;
 
-// @public (undocumented)
+// @public
 export const DefaultPaths: Paths;
 
-// @public (undocumented)
+// @public
 export interface ElectronBinary {
-    // (undocumented)
     alreadyExtracted: boolean;
-    // (undocumented)
     path: string;
 }
 
 // @public
 export class ElectronVersions extends BaseVersions {
-    // (undocumented)
     static create(paths?: Partial<Paths>, options?: ElectronVersionsCreateOptions): Promise<ElectronVersions>;
-    // (undocumented)
     fetch(): Promise<void>;
-    // (undocumented)
     inMajor(major: number): SemVer[];
-    // (undocumented)
     inRange(a: SemOrStr, b: SemOrStr): SemVer[];
-    // (undocumented)
     isVersion(ver: SemOrStr): boolean;
-    // (undocumented)
     get latest(): SemVer | undefined;
-    // (undocumented)
     get latestStable(): SemVer | undefined;
-    // (undocumented)
     get obsoleteMajors(): number[];
-    // (undocumented)
     get prereleaseMajors(): number[];
-    // (undocumented)
     get stableMajors(): number[];
-    // (undocumented)
     get supportedMajors(): number[];
-    // (undocumented)
     get versions(): SemVer[];
 }
 
-// @public (undocumented)
+// @public
 export interface ElectronVersionsCreateOptions {
     ignoreCache?: boolean;
     initialVersions?: unknown;
 }
 
-// @public (undocumented)
+// @public
 export class Fiddle {
-    constructor(mainPath: string, // /path/to/main.js
+    constructor(
+    mainPath: string, // /path/to/main.js
     source: string);
-    // (undocumented)
     readonly mainPath: string;
-    // (undocumented)
     remove(): Promise<void>;
-    // (undocumented)
     readonly source: string;
 }
 
-// @public (undocumented)
+// @public
 export class FiddleFactory {
     constructor(fiddles?: string);
-    // (undocumented)
     create(src: FiddleSource): Promise<Fiddle | undefined>;
-    // (undocumented)
     fromEntries(src: Iterable<[string, string]>): Promise<Fiddle>;
-    // (undocumented)
     fromFolder(source: string): Promise<Fiddle>;
-    // (undocumented)
     fromGist(gistId: string): Promise<Fiddle>;
-    // (undocumented)
     fromRepo(url: string, checkout?: string): Promise<Fiddle>;
 }
 
@@ -130,76 +95,56 @@ export type FiddleSource = Fiddle | string | Iterable<[string, string]>;
 // @public
 export class Installer extends EventEmitter {
     constructor(pathsIn?: Partial<Paths>);
-    // (undocumented)
     ensureDownloaded(version: string, opts?: Partial<InstallerParams>): Promise<ElectronBinary>;
-    // (undocumented)
     static execSubpath(platform?: string): string;
-    // (undocumented)
     static getExecPath(folder: string): string;
-    // (undocumented)
     install(version: string, opts?: Partial<InstallerParams>): Promise<string>;
     get installedVersion(): string | undefined;
     remove(version: string): Promise<void>;
-    // (undocumented)
     state(version: string): InstallState;
 }
 
-// @public (undocumented)
+// @public
 export interface InstallerParams {
-    // (undocumented)
     mirror: Mirrors;
-    // (undocumented)
     progressCallback: (progress: ProgressObject) => void;
 }
 
 // @public
 export enum InstallState {
-    // (undocumented)
     downloaded = "downloaded",
-    // (undocumented)
     downloading = "downloading",
-    // (undocumented)
     installed = "installed",
-    // (undocumented)
     installing = "installing",
-    // (undocumented)
     missing = "missing"
 }
 
-// @public (undocumented)
+// @public
 export interface InstallStateEvent {
-    // (undocumented)
     state: InstallState;
-    // (undocumented)
     version: string;
 }
 
-// @public (undocumented)
+// @public
 export interface Mirrors {
-    // (undocumented)
     electronMirror: string;
-    // (undocumented)
     electronNightlyMirror: string;
 }
 
-// @public (undocumented)
+// @public
 export interface Paths {
-    // (undocumented)
     readonly electronDownloads: string;
-    // (undocumented)
     readonly electronInstall: string;
-    // (undocumented)
     readonly fiddles: string;
-    // (undocumented)
     readonly versionsCache: string;
 }
 
-// @public (undocumented)
+// @public
 export type ProgressObject = {
     percent: number;
 };
 
-// @public (undocumented)
+// @public
 export interface ReleaseInfo {
     chrome: string;
     date: string;
@@ -213,51 +158,41 @@ export interface ReleaseInfo {
     zlib: string;
 }
 
-// @public (undocumented)
+// @public
 export function runFromCommandLine(argv: string[]): Promise<void>;
 
-// @public (undocumented)
+// @public
 export class Runner {
-    // (undocumented)
     bisect(version_a: string | SemVer, version_b: string | SemVer, fiddleIn: FiddleSource, opts?: RunnerSpawnOptions): Promise<BisectResult>;
-    // (undocumented)
     static create(opts?: {
         installer?: Installer;
         fiddleFactory?: FiddleFactory;
         paths?: Partial<Paths>;
         versions?: Versions;
     }): Promise<Runner>;
-    // (undocumented)
     static displayResult(result: TestResult): string;
-    // (undocumented)
     run(version: string | SemVer, fiddle: FiddleSource, opts?: RunnerSpawnOptions): Promise<TestResult>;
-    // (undocumented)
     spawn(versionIn: string | SemVer, fiddleIn: FiddleSource, opts?: RunnerSpawnOptions): Promise<ChildProcess>;
 }
 
-// @public (undocumented)
+// @public
 export interface RunnerOptions {
-    // (undocumented)
     args?: string[];
-    // (undocumented)
     headless?: boolean;
-    // (undocumented)
     out?: Writable;
-    // (undocumented)
     showConfig?: boolean;
 }
 
-// @public (undocumented)
+// @public
 export type RunnerSpawnOptions = SpawnOptions & RunnerOptions;
 
-// @public (undocumented)
+// @public
 export type SemOrStr = SemVer | string;
 
 export { SemVer }
 
-// @public (undocumented)
+// @public
 export interface TestResult {
-    // (undocumented)
     status: 'test_passed' | 'test_failed' | 'test_error' | 'system_error';
 }
 

src/command-line.ts

@@ -5,6 +5,11 @@ import { ElectronVersions } from './versions';
 import { Fiddle, FiddleFactory } from './fiddle';
 import { Runner } from './runner';
 
+/**
+ * Function handles command-line arguments, creates instances of necessary objects and
+ * executes specific commands based on the arguments provided.
+ * It logs debug information and exits the process if invalid parameters are detected.
+ */
 export async function runFromCommandLine(argv: string[]): Promise<void> {
   const d = debug('fiddle-core:runFromCommandLine');
 

src/fiddle.ts

@@ -12,12 +12,16 @@ function hashString(str: string): string {
   return md5sum.digest('hex');
 }
 
+/** This class represents a fiddle */
 export class Fiddle {
   constructor(
+    /** It serves as the entry point or the primary script file for the fiddle */
     public readonly mainPath: string, // /path/to/main.js
+    /** Is the cource of the fiddle */
     public readonly source: string,
   ) {}
 
+  /** This method deletes the fiddle from the system */
   public remove(): Promise<void> {
     return fs.remove(path.dirname(this.mainPath));
   }
@@ -31,13 +35,19 @@ export class Fiddle {
  */
 export type FiddleSource = Fiddle | string | Iterable<[string, string]>;
 
+/**
+ * This class is responsible for creating instances of the Fiddle class
+ * and it has methods to create a fiddle from various source
+ */
 export class FiddleFactory {
   constructor(private readonly fiddles: string = DefaultPaths.fiddles) {}
 
+  /** This method creates a Fiddle instance by fetching a GitHub Gist and cloning it into a temporary directory, */
   public async fromGist(gistId: string): Promise<Fiddle> {
     return this.fromRepo(`https://gist.github.com/${gistId}.git`);
   }
 
+  /** This method creates a Fiddle instance by making a temporary copy of the fiddle from a specified source */
   public async fromFolder(source: string): Promise<Fiddle> {
     const d = debug('fiddle-core:FiddleFactory:fromFolder');
 
@@ -55,6 +65,11 @@ export class FiddleFactory {
     return new Fiddle(path.join(folder, 'main.js'), source);
   }
 
+  /**
+   * This method creates a Fiddle instance by cloning a Git repository into a temporary directory,
+   * optionally checking out a specified branch,
+   * and setting the main file path based on the cloned files.
+   */
   public async fromRepo(url: string, checkout = 'master'): Promise<Fiddle> {
     const d = debug('fiddle-core:FiddleFactory:fromRepo');
     const folder = path.join(this.fiddles, hashString(url));
@@ -74,6 +89,10 @@ export class FiddleFactory {
     return new Fiddle(path.join(folder, 'main.js'), url);
   }
 
+  /**
+   * This method creates a Fiddle instance by saving a collection of filename-content pairs to a temporary directory
+   * and setting the main file path accordingly.
+   */
   public async fromEntries(src: Iterable<[string, string]>): Promise<Fiddle> {
     const d = debug('fiddle-core:FiddleFactory:fromEntries');
     const map = new Map<string, string>(src);
@@ -95,6 +114,7 @@ export class FiddleFactory {
     return new Fiddle(path.join(folder, 'main.js'), 'entries');
   }
 
+  /** This method determines the source type and calls the appropriate method to create the fiddle */
   public async create(src: FiddleSource): Promise<Fiddle | undefined> {
     if (src instanceof Fiddle) return src;