udpate comments; fix naming

Author: mProjectsCode

packages/core/src/api/API.ts

@@ -56,7 +56,7 @@ import {
 	type FieldOptionMap,
 	FieldType,
 	type InlineFieldType,
-	type APIConfigs,
+	type InputFieldOptions,
 	isFieldTypeAllowedInline,
 	type JsViewFieldOptions,
 	NotePosition,
@@ -120,10 +120,10 @@ export abstract class API<Plugin extends IPlugin> {
 	/**
 	 * Creates a field of a given type.
 	 *
-	 * @param type
-	 * @param filePath
+	 * @param type the type of the field
+	 * @param filePath the file path that the field is located in, or an empty string if it is not in a file
 	 * @param options
-	 * @param honorExcludedSetting
+	 * @param honorExcludedSetting whether to honor the excluded folders settings for this field
 	 */
 	public createField<Type extends FieldType>(
 		type: Type,
@@ -178,12 +178,12 @@ export abstract class API<Plugin extends IPlugin> {
 	 * Creates an inline field from a string.
 	 * Will throw an error if the string is not a valid declaration.
 	 *
-	 * @param fieldString
-	 * @param filePath
-	 * @param scope
-	 * @param renderChildType
-	 * @param position
-	 * @param honorExcludedSetting
+	 * @param fieldString the declaration string of the field
+	 * @param filePath the file path that the field is located in
+	 * @param scope optional bind target scope
+	 * @param renderChildType the render child type, default INLINE
+	 * @param position an optional note position
+	 * @param honorExcludedSetting whether to honor the excluded folders settings for this field
 	 */
 	public createInlineFieldFromString(
 		fieldString: string,
@@ -234,13 +234,13 @@ export abstract class API<Plugin extends IPlugin> {
 	 * Creates an inline field of a given type and string.
 	 * Will throw an error if the string is not a valid inline field type.
 	 *
-	 * @param type
-	 * @param filePath
-	 * @param declaration
-	 * @param scope
-	 * @param renderChildType
-	 * @param position
-	 * @param honorExcludedSetting
+	 * @param type the field type
+	 * @param declaration the declaration string of the field
+	 * @param filePath the file path that the field is located in
+	 * @param scope optional bind target scope
+	 * @param renderChildType the render child type, default INLINE
+	 * @param position an optional note position
+	 * @param honorExcludedSetting whether to honor the excluded folders settings for this field
 	 */
 	public createInlineFieldOfTypeFromString(
 		type: InlineFieldType,
@@ -307,7 +307,13 @@ export abstract class API<Plugin extends IPlugin> {
 		});
 	}
 
-	public createInputFieldMountable(filePath: string, options: APIConfigs): InputFieldMountable {
+	/**
+	 * Creates an input field from an options object.
+	 *
+	 * @param filePath the file path that the field is located in or an empty string
+	 * @param options
+	 */
+	public createInputFieldMountable(filePath: string, options: InputFieldOptions): InputFieldMountable {
 		validate(
 			z.object({
 				filePath: V_FilePath,
@@ -335,6 +341,12 @@ export abstract class API<Plugin extends IPlugin> {
 		return new InputFieldMountable(this.plugin, uuid, filePath, options.renderChildType, declaration);
 	}
 
+	/**
+	 * Creates a view field from an options object.
+	 *
+	 * @param filePath the file path that the field is located in or an empty string
+	 * @param options
+	 */
 	public createViewFieldMountable(filePath: string, options: ViewFieldOptions): ViewFieldMountable {
 		validate(
 			z.object({
@@ -363,6 +375,12 @@ export abstract class API<Plugin extends IPlugin> {
 		return new ViewFieldMountable(this.plugin, uuid, filePath, options.renderChildType, declaration);
 	}
 
+	/**
+	 * Creates a JS view field from an options object.
+	 *
+	 * @param filePath the file path that the field is located in or an empty string
+	 * @param options
+	 */
 	public createJsViewFieldMountable(filePath: string, options: JsViewFieldOptions): JsViewFieldMountable {
 		validate(
 			z.object({
@@ -387,6 +405,12 @@ export abstract class API<Plugin extends IPlugin> {
 		return new JsViewFieldMountable(this.plugin, uuid, filePath, declaration);
 	}
 
+	/**
+	 * Creates a table from an options object.
+	 *
+	 * @param filePath the file path that the field is located in or an empty string
+	 * @param options
+	 */
 	public createTableMountable(filePath: string, options: TableOptions): TableMountable {
 		validate(
 			z.object({
@@ -404,6 +428,12 @@ export abstract class API<Plugin extends IPlugin> {
 		return new TableMountable(this.plugin, uuid, filePath, options.bindTarget, options.tableHead, options.columns);
 	}
 
+	/**
+	 * Creates a button group from an options object.
+	 *
+	 * @param filePath the file path that the field is located in or an empty string
+	 * @param options
+	 */
 	public createButtonGroupMountable(filePath: string, options: ButtonGroupOptions): ButtonGroupMountable {
 		validate(
 			z.object({
@@ -435,6 +465,12 @@ export abstract class API<Plugin extends IPlugin> {
 		);
 	}
 
+	/**
+	 * Creates a button from an options object.
+	 *
+	 * @param filePath the file path that the field is located in or an empty string
+	 * @param options
+	 */
 	public createButtonMountable(filePath: string, options: ButtonOptions): ButtonMountable {
 		validate(
 			z.object({
@@ -459,6 +495,12 @@ export abstract class API<Plugin extends IPlugin> {
 		return new ButtonMountable(this.plugin, uuid, filePath, declaration, options.position, options.isPreview);
 	}
 
+	/**
+	 * Creates a meta bind embed fields from an options object.
+	 *
+	 * @param filePath the file path that the field is located in or an empty string
+	 * @param options
+	 */
 	public createEmbedMountable(filePath: string, options: EmbedOptions): EmbedMountable {
 		validate(
 			z.object({
@@ -475,6 +517,11 @@ export abstract class API<Plugin extends IPlugin> {
 		return new EmbedMountable(this.plugin, uuid, filePath, options.depth, options.content);
 	}
 
+	/**
+	 * Creates an excluded notification mountable for the excluded folders setting.
+	 *
+	 * @param filePath the file path that the field is located in or an empty string
+	 */
 	public createExcludedMountable(filePath: string): ExcludedMountable {
 		validate(
 			z.object({
@@ -490,7 +537,7 @@ export abstract class API<Plugin extends IPlugin> {
 	}
 
 	/**
-	 * Gets the prefix of a given widget type. (e.g. INPUT or VIEW)
+	 * Gets the prefix of a given widget type. (e.g. INPUT or VIEW).
 	 *
 	 * @param fieldType
 	 */
@@ -523,7 +570,7 @@ export abstract class API<Plugin extends IPlugin> {
 	 * Checks if a string is a declaration of a given widget type.
 	 *
 	 * @param fieldType
-	 * @param str
+	 * @param str the declaration string
 	 */
 	public isInlineFieldDeclaration(fieldType: FieldType, str: string): boolean {
 		validate(
@@ -545,9 +592,8 @@ export abstract class API<Plugin extends IPlugin> {
 
 	/**
 	 * Checks if a string is any declaration and if yes returns the widget type.
-	 * This does not use {@link isInlineFieldDeclaration} because of performance reasons.
 	 *
-	 * @param str
+	 * @param str the declaration string
 	 */
 	public isInlineFieldDeclarationAndGetType(str: string): InlineFieldType | undefined {
 		validate(
@@ -576,6 +622,11 @@ export abstract class API<Plugin extends IPlugin> {
 		return undefined;
 	}
 
+	/**
+	 * Creates a signal.
+	 *
+	 * @param value
+	 */
 	public createSignal<T>(value: T): Signal<T> {
 		return new Signal<T>(value);
 	}
@@ -749,6 +800,12 @@ export abstract class API<Plugin extends IPlugin> {
 		});
 	}
 
+	/**
+	 * Creates a note position from a line start and line end number.
+	 *
+	 * @param lineStart
+	 * @param lineEnd
+	 */
 	public createNotePosition(lineStart: number, lineEnd: number): NotePosition {
 		validate(
 			z.object({

packages/core/src/api/Validators.ts

@@ -37,7 +37,7 @@ import {
 	type ButtonOptions,
 	type EmbedOptions,
 	FieldType,
-	type APIConfigs,
+	type InputFieldOptions,
 	type JsViewFieldOptions,
 	NotePosition,
 	RenderChildType,
@@ -195,7 +195,7 @@ export const V_SimpleInlineButtonDeclaration = schemaForType<SimpleButtonGroupDe
 	}),
 );
 
-export const V_InputFieldOptions = schemaForType<APIConfigs>()(
+export const V_InputFieldOptions = schemaForType<InputFieldOptions>()(
 	z.object({
 		renderChildType: V_RenderChildType,
 		declaration: z.union([z.string(), V_SimpleInputFieldDeclaration]),

packages/core/src/config/APIConfigs.ts

@@ -25,7 +25,7 @@ export enum FieldType {
 	EXCLUDED = 'EXCLUDED',
 }
 
-export interface APIConfigs {
+export interface InputFieldOptions {
 	renderChildType: RenderChildType;
 	declaration: SimpleInputFieldDeclaration | string;
 	scope?: BindTargetScope | undefined;
@@ -82,7 +82,7 @@ export interface EmbedOptions {
 }
 
 export interface FieldOptionMap {
-	[FieldType.INPUT]: APIConfigs;
+	[FieldType.INPUT]: InputFieldOptions;
 	[FieldType.VIEW]: ViewFieldOptions;
 	[FieldType.JS_VIEW]: JsViewFieldOptions;
 	[FieldType.TABLE]: TableOptions;

packages/obsidian/src/ObsidianAPI.ts

@@ -13,10 +13,10 @@ import { Signal } from 'packages/core/src/utils/Signal';
 import { getJsEnginePluginAPI } from 'packages/obsidian/src/ObsUtils';
 import { type ReactiveComponent } from 'jsEngine/api/reactive/ReactiveComponent';
 import { type Mountable } from 'packages/core/src/utils/Mountable';
-import { type FieldType, isFieldTypeAllowedInline } from 'packages/core/src/config/APIConfigs';
+import { type InlineFieldType, isFieldTypeAllowedInline } from 'packages/core/src/config/APIConfigs';
 
 /**
- * Either {@link MarkdownPostProcessorContext} or {@link Component}.
+ * Either a [Component](https://docs.obsidian.md/Reference/TypeScript+API/Component) or a [MarkdownPostProcessorContext](https://docs.obsidian.md/Reference/TypeScript+API/MarkdownPostProcessorContext).
  */
 export interface ComponentLike {
 	addChild(child: Component): void;
@@ -38,48 +38,60 @@ export class ObsidianAPI extends API<MetaBindPlugin> {
 		super(plugin);
 	}
 
-	public wrapInMDRC(field: Mountable, containerEl: HTMLElement, component: ComponentLike): MountableMDRC {
+	/**
+	 * Wraps any mountable in a [MarkdownRenderChild](https://docs.obsidian.md/Reference/TypeScript+API/MarkdownRenderChild)
+	 * and adds it as a child to the passed in {@link ComponentLike}.
+	 *
+	 * A {@link ComponentLike} is either a [Component](https://docs.obsidian.md/Reference/TypeScript+API/Component) or a [MarkdownPostProcessorContext](https://docs.obsidian.md/Reference/TypeScript+API/MarkdownPostProcessorContext)
+	 *
+	 * @param mountable the mountable to wrap in a [MarkdownRenderChild](https://docs.obsidian.md/Reference/TypeScript+API/MarkdownRenderChild)
+	 * @param containerEl the element to mount the [MarkdownRenderChild](https://docs.obsidian.md/Reference/TypeScript+API/MarkdownRenderChild) to
+	 * @param component the {@link ComponentLike} to register the [MarkdownRenderChild](https://docs.obsidian.md/Reference/TypeScript+API/MarkdownRenderChild) to
+	 */
+	public wrapInMDRC(mountable: Mountable, containerEl: HTMLElement, component: ComponentLike): MountableMDRC {
 		validate(
 			z.object({
 				field: V_Mountable,
 				containerEl: V_HTMLElement,
 				component: V_ComponentLike,
 			}),
 			{
-				field: field,
+				field: mountable,
 				containerEl: containerEl,
 				component: component,
 			},
 		);
 
-		const mdrc = new MountableMDRC(this.plugin, field, containerEl);
+		const mdrc = new MountableMDRC(this.plugin, mountable, containerEl);
 		component.addChild(mdrc);
 
 		return mdrc;
 	}
 
 	/**
-	 * Creates a MDRC widget from a given widget type.
+	 * Creates a CM6 widget from a given widget type.
+	 *
+	 * This is only useful fur use in a CodeMirror plugin.
 	 *
-	 * @param mdrcType
+	 * @param inlineFieldType
 	 * @param content
 	 * @param filePath
 	 * @param component
 	 */
 	public constructMDRCWidget(
-		mdrcType: FieldType,
+		inlineFieldType: InlineFieldType,
 		content: string,
 		filePath: string,
 		component: Component,
 	): MarkdownRenderChildWidget {
-		if (isFieldTypeAllowedInline(mdrcType)) {
-			return new MarkdownRenderChildWidget(mdrcType, content, filePath, component, this.plugin);
+		if (isFieldTypeAllowedInline(inlineFieldType)) {
+			return new MarkdownRenderChildWidget(inlineFieldType, content, filePath, component, this.plugin);
 		}
 
 		throw new MetaBindInternalError({
 			errorLevel: ErrorLevel.CRITICAL,
 			effect: 'failed to construct mdrc',
-			cause: `Invalid inline mdrc type "${mdrcType}"`,
+			cause: `Invalid inline field type "${inlineFieldType}"`,
 		});
 	}
 
@@ -88,9 +100,9 @@ export class ObsidianAPI extends API<MetaBindPlugin> {
 	 *
 	 * This requires JS Engine to be installed and enabled!
 	 *
-	 * @param bindTargets
-	 * @param lifecycleHook
-	 * @param callback
+	 * @param bindTargets the bind targets to listen to
+	 * @param lifecycleHook a [Component](https://docs.obsidian.md/Reference/TypeScript+API/Component)
+	 * @param callback the callback to call with all the values of the bind targets when one of them changes. What ever this callback returns will be rendered by the reactive component.
 	 */
 	public reactiveMetadata(
 		bindTargets: BindTargetDeclaration[],