Skip to content

chore: add comments documenting public API #83

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 11 commits into
base: main
Choose a base branch
from
Open

chore: add comments documenting public API #83

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
00d485d
Adding comment for the function runFromCommandLine
Jun 23, 2023
49b20f1
Addressed the lint and other issues, rolled back to the original vers…
Jun 23, 2023
5fc3d76
Added comments in fiddle.ts and added caret prefix for api-extractor
Jun 23, 2023
75d986c
Added comments in installer.ts
Jun 24, 2023
d8e4627
Fixed lint issues in installer.ts
Jun 24, 2023
14e18f0
Added comments on paths.ts
Jun 24, 2023
90ece72
Added comments to runner.ts file
Jun 24, 2023
6e3e701
Added comments to the file versions.ts
Jun 24, 2023
b35f672
Made changes as PR review comments
abhishekgite446 Jun 29, 2023
d70a743
Reverting changes from yarn.lock
abhishekgite446 Jun 29, 2023
a1e71f6
Amended comments based on Review comments
abhishekgite446 Jul 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 21 additions & 86 deletions etc/fiddle-core.api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>;
}

Expand All @@ -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;
Expand All @@ -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';
}

Expand Down
5 changes: 5 additions & 0 deletions src/command-line.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,11 @@ import { ElectronVersions } from './versions';
import { Fiddle, FiddleFactory } from './fiddle';
import { Runner } from './runner';

/**
* This 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');

Expand Down
20 changes: 20 additions & 0 deletions src/fiddle.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
/** It represents the code */
public readonly source: string,
) {}

/** This method deletes the fiddle from the system */
public remove(): Promise<void> {
return fs.remove(path.dirname(this.mainPath));
}
Expand All @@ -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');

Expand All @@ -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,
* checking out a specified branch (default: 'master'),
* 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));
Expand All @@ -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);
Expand All @@ -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;

Expand Down
Loading