minor refactor; add more comments

Author: mProjectsCode

JsEngine.d.ts

@@ -1,9 +1,8 @@
 import { type MarkdownPostProcessorContext, MarkdownRenderChild, Menu, setIcon, type TAbstractFile, TFile } from 'obsidian';
 import type JsEnginePlugin from './main';
-import { type ExecutionContext } from './ArgumentManager';
 
-import { type JsExecution } from './engine/JsExecution';
-import { ResultRenderer } from './ResultRenderer';
+import { type JsExecutionContext, type JsExecution } from './engine/JsExecution';
+import { ResultRenderer } from './engine/ResultRenderer';
 
 export class JsMDRC extends MarkdownRenderChild {
 	plugin: JsEnginePlugin;
@@ -35,7 +34,7 @@ export class JsMDRC extends MarkdownRenderChild {
 		}
 	}
 
-	buildExecutionContext(): ExecutionContext {
+	buildExecutionContext(): JsExecutionContext {
 		console.log(this.ctx);
 		const file = this.getExecutionFile()!;
 		return {
@@ -45,7 +44,7 @@ export class JsMDRC extends MarkdownRenderChild {
 		};
 	}
 
-	async tryRun(context: ExecutionContext): Promise<JsExecution> {
+	async tryRun(context: JsExecutionContext): Promise<JsExecution> {
 		return this.plugin.jsEngine.execute({
 			code: this.content,
 			context: context,

bun.lockb

@@ -51,8 +51,7 @@ export class API {
 	 *
 	 * @param path the vault relative path of the file to import
 	 */
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	public async importJs(path: string): Promise<any> {
+	public async importJs(path: string): Promise<unknown> {
 		let fullPath = this.app.vault.adapter.getResourcePath(path);
 		if (!fullPath.includes('?')) {
 			const scriptFile = this.app.metadataCache.getFirstLinkpathDest(path, '');
@@ -72,6 +71,13 @@ export class API {
 		return this.app.plugins.getPlugin(pluginId);
 	}
 
+	/**
+	 * Creates a reactive component.
+	 * Reactive components are useful for creating dynamic content.
+	 *
+	 * @param fn the function to rerun. It's return value will be rendered.
+	 * @param initialArgs the initial arguments (for the first render) to pass to the function.
+	 */
 	public reactive(fn: JsFunc, ...initialArgs: unknown[]): ReactiveComponent {
 		return new ReactiveComponent(fn, initialArgs);
 	}

jsEngine/ArgumentManager.ts

@@ -2,7 +2,7 @@ import { type API } from './API';
 import { type EngineExecutionParams } from '../engine/Engine';
 import { type JsExecution } from '../engine/JsExecution';
 import { type Component, TFile } from 'obsidian';
-import { ResultRenderer } from '../ResultRenderer';
+import { ResultRenderer } from '../engine/ResultRenderer';
 
 /**
  * The internal API provides access to some of js engines internals.
@@ -14,14 +14,32 @@ export class InternalAPI {
 		this.apiInstance = apiInstance;
 	}
 
+	/**
+	 * Executes the given code.
+	 *
+	 * @param params
+	 */
 	public async execute(params: EngineExecutionParams): Promise<JsExecution> {
 		return await this.apiInstance.plugin.jsEngine.execute(params);
 	}
 
+	/**
+	 * Creates a result renderer.
+	 *
+	 * @param container
+	 * @param sourcePath
+	 * @param component
+	 */
 	public createRenderer(container: HTMLElement, sourcePath: string, component: Component): ResultRenderer {
 		return new ResultRenderer(this.apiInstance.plugin, container, sourcePath, component);
 	}
 
+	/**
+	 * Load and execute the given file.
+	 *
+	 * @param path
+	 * @param params
+	 */
 	public async executeFile(path: string, params: Omit<EngineExecutionParams, 'code'>): Promise<JsExecution> {
 		const file = this.apiInstance.app.vault.getAbstractFileByPath(path);
 		if (!file || !(file instanceof TFile)) {

jsEngine/JsMDRC.ts

@@ -25,6 +25,9 @@ export class LibAPI {
 		this.apiInstance = apiInstance;
 	}
 
+	/**
+	 * Get the [ParsiNOM](https://github.com/mProjectsCode/parsiNOM) library.
+	 */
 	public parsinom(): LibParsiNOM {
 		return {
 			P: P,
@@ -36,8 +39,10 @@ export class LibAPI {
 		};
 	}
 
-	// eslint-disable-next-line @typescript-eslint/no-explicit-any
-	public itertools(): any {
+	/**
+	 * Get the [itertools-ts](https://github.com/Smoren/itertools-ts) library.
+	 */
+	public itertools(): typeof IterTools {
 		return IterTools;
 	}
 }

jsEngine/ResultRenderer.ts

@@ -1,11 +1,23 @@
 import { type MarkdownElementType } from './MarkdownElementType';
 import { MarkdownString } from './MarkdownString';
 
+/**
+ * @internal
+ */
 export abstract class AbstractMarkdownElement {
+	/**
+	 * Converts the element to a string.
+	 */
 	abstract toString(): string;
 
+	/**
+	 * @internal
+	 */
 	abstract getType(): MarkdownElementType;
 
+	/**
+	 * Converts the element to a {@link MarkdownString}.
+	 */
 	toMarkdown(): MarkdownString {
 		return new MarkdownString(this.toString());
 	}

jsEngine/api/API.ts

@@ -2,6 +2,9 @@ import { AbstractMarkdownElement } from './AbstractMarkdownElement';
 import { MarkdownElementType } from './MarkdownElementType';
 import { AbstractMarkdownLiteral } from './AbstractMarkdownLiteral';
 
+/**
+ * @internal
+ */
 export abstract class AbstractMarkdownElementContainer extends AbstractMarkdownElement {
 	markdownElements: AbstractMarkdownElement[];
 
@@ -11,12 +14,21 @@ export abstract class AbstractMarkdownElementContainer extends AbstractMarkdownE
 		this.markdownElements = [];
 	}
 
+	/**
+	 * @internal
+	 */
 	abstract allowElement(element: AbstractMarkdownElement): boolean;
 
 	public getType(): MarkdownElementType {
 		return MarkdownElementType.NON_LITERAL;
 	}
 
+	/**
+	 * Adds a child element to the container.
+	 *
+	 * @param element
+	 * @throws Error if the element is not allowed in the container.
+	 */
 	addElement(element: AbstractMarkdownElement): void {
 		if (this.allowElement(element)) {
 			this.markdownElements.push(element);
@@ -96,6 +108,9 @@ export abstract class AbstractMarkdownElementContainer extends AbstractMarkdownE
 // LITERALS
 // --------------------------------------------
 
+/**
+ * Represents a piece of pure markdown text.
+ */
 export class TextElement extends AbstractMarkdownLiteral {
 	content: string;
 	bold: boolean;
@@ -134,6 +149,9 @@ export class TextElement extends AbstractMarkdownLiteral {
 	}
 }
 
+/**
+ * Represents an inline markdown code block.
+ */
 export class CodeElement extends AbstractMarkdownLiteral {
 	content: string;
 
@@ -152,6 +170,9 @@ export class CodeElement extends AbstractMarkdownLiteral {
 // NON LITERALS
 // --------------------------------------------
 
+/**
+ * Represents a markdown heading.
+ */
 export class HeadingElement extends AbstractMarkdownElementContainer {
 	level: number;
 
@@ -171,6 +192,9 @@ export class HeadingElement extends AbstractMarkdownElementContainer {
 	}
 }
 
+/**
+ * Represents a markdown paragraph.
+ */
 export class ParagraphElement extends AbstractMarkdownElementContainer {
 	constructor(content: string) {
 		super();
@@ -187,6 +211,9 @@ export class ParagraphElement extends AbstractMarkdownElementContainer {
 	}
 }
 
+/**
+ * Represents a markdown code block.
+ */
 export class CodeBlockElement extends AbstractMarkdownElementContainer {
 	language: string;
 
@@ -206,6 +233,9 @@ export class CodeBlockElement extends AbstractMarkdownElementContainer {
 	}
 }
 
+/**
+ * Represents a markdown block quote.
+ */
 export class BlockQuoteElement extends AbstractMarkdownElementContainer {
 	public allowElement(_: AbstractMarkdownElement): boolean {
 		return true;
@@ -216,6 +246,9 @@ export class BlockQuoteElement extends AbstractMarkdownElementContainer {
 	}
 }
 
+/**
+ * Represents a markdown callout.
+ */
 export class CalloutElement extends AbstractMarkdownElementContainer {
 	title: string;
 	type: string;
@@ -238,6 +271,9 @@ export class CalloutElement extends AbstractMarkdownElementContainer {
 	}
 }
 
+/**
+ * Represents a markdown table.
+ */
 export class TableElement extends AbstractMarkdownElementContainer {
 	header: string[];
 	body: string[][];